diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index 5ba828f..aac3081 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -26,7 +26,7 @@ jobs: python-version: '3.9' - name: Install dependencies run: | - python -m pip install --upgrade meson + python -m pip install --upgrade meson PyYAML sudo apt update sudo apt install -y \ doxygen libxcb-xkb-dev valgrind ninja-build \ diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml index c57a0d7..cde0989 100644 --- a/.github/workflows/macos.yml +++ b/.github/workflows/macos.yml @@ -23,7 +23,7 @@ jobs: python-version: '3.9' - name: Install dependencies run: | - python -m pip install --upgrade meson + python -m pip install --upgrade meson PyYAML brew install libxml2 doxygen bison ninja brew link bison --force env: diff --git a/doc/cool-uris.yaml b/doc/cool-uris.yaml new file mode 100644 index 0000000..b739ee5 --- /dev/null +++ b/doc/cool-uris.yaml @@ -0,0 +1,63 @@ +# WARNING: This file is autogenerated by: scripts/ensure-stable-doc-urls.py +# Do not edit manually. +annotated.html: [] +classes.html: [] +deprecated.html: [] +dir_63ce773eee1f9b680e6e312b48cc99ca.html: [] +dir_891596f32582d3133e8915e72908625f.html: [] +dir_d44c64559bbebec7f509842c48db8b23.html: [] +dir_e68e8157741866f444e17edd764ebbae.html: [] +files.html: [] +functions.html: [] +functions_func.html: [] +functions_type.html: [] +functions_vars.html: [] +globals.html: [] +globals_defs.html: [] +globals_enum.html: [] +globals_eval.html: [] +globals_func.html: [] +globals_type.html: [] +graph_legend.html: [] +group__components.html: [] +group__compose.html: [] +group__context.html: [] +group__include-path.html: [] +group__keymap.html: [] +group__keysyms.html: [] +group__logging.html: [] +group__registry.html: [] +group__state.html: [] +group__x11.html: [] +index.html: [] +keymap-text-format-v1.html: +- md_doc_keymap_format_text_v1.html +md_doc_quick_guide.html: [] +md_doc_user_configuration.html: [] +modules.html: [] +pages.html: [] +rule-file-format.html: +- md_doc_rules_format.html +structrxkb__context.html: [] +structrxkb__iso3166__code.html: [] +structrxkb__iso639__code.html: [] +structrxkb__layout.html: [] +structrxkb__model.html: [] +structrxkb__option.html: [] +structrxkb__option__group.html: [] +structxkb__compose__state.html: [] +structxkb__compose__table.html: [] +structxkb__context.html: [] +structxkb__keymap.html: [] +structxkb__rule__names.html: [] +structxkb__state.html: [] +todo.html: [] +xkb-intro.html: [] +xkbcommon-compatibility.html: +- md_doc_compat.html +xkbcommon-compose_8h.html: [] +xkbcommon-keysyms_8h.html: [] +xkbcommon-names_8h.html: [] +xkbcommon-x11_8h.html: [] +xkbcommon_8h.html: [] +xkbregistry_8h.html: [] diff --git a/meson.build b/meson.build index b64427d..2cd1ee7 100644 --- a/meson.build +++ b/meson.build @@ -819,15 +819,34 @@ You can disable the documentation with -Denable-docs=false.''') ) # TODO: Meson should provide this. docdir = get_option('datadir')/'doc'/meson.project_name() - custom_target( + doc_gen = custom_target( 'doc', input: [doxyfile] + doxygen_input, output: 'html', - command: [doxygen_wrapper, doxygen, meson.current_build_dir()/'Doxyfile', meson.current_source_dir()], + command: [ + doxygen_wrapper, + doxygen, + meson.current_build_dir()/'Doxyfile', + meson.current_source_dir(), + ], install: true, install_dir: docdir, build_by_default: true, ) + ensure_stable_urls = find_program('scripts'/'ensure-stable-doc-urls.py') + custom_target( + 'doc-cool-uris', + input: [doc_gen, 'doc'/'cool-uris.yaml'], + output: 'html-xtra', + command: [ + ensure_stable_urls, + 'generate-redirections', + meson.current_source_dir()/'doc'/'cool-uris.yaml', + meson.current_build_dir()/'html' + ], + install: false, + build_by_default: true, + ) endif configure_file(output: 'config.h', configuration: configh_data) diff --git a/scripts/ensure-stable-doc-urls.py b/scripts/ensure-stable-doc-urls.py new file mode 100755 index 0000000..27f8232 --- /dev/null +++ b/scripts/ensure-stable-doc-urls.py @@ -0,0 +1,232 @@ +#!/usr/bin/env python3 + +# Doc URLs may change with time because they depend on Doxygen machinery. +# This is unfortunate because it is good practice to keep valid URLs. +# See: “Cool URIs don’t change” at https://www.w3.org/Provider/Style/URI.html. +# +# There is no built-in solution in Doxygen that we are aware of. +# The solution proposed here is to maintain a registry of all URLs and manage +# legacy URLs as redirections to their canonical page. + +import argparse +from enum import IntFlag +import glob +from itertools import chain +from pathlib import Path +from string import Template +from typing import NamedTuple, Sequence + +import yaml + + +class Update(NamedTuple): + new: str + old: str + + +class ExitCode(IntFlag): + NORMAL = 0 + INVALID_UPDATES = 1 << 4 + MISSING_UPDATES = 1 << 5 + + +THIS_SCRIPT_PATH = Path(__file__) +RELATIVE_SCRIPT_PATH = THIS_SCRIPT_PATH.relative_to(THIS_SCRIPT_PATH.parent.parent) + +REDIRECTION_DELAY = 6 # in seconds. Note: at least 6s for accessibility + +# NOTE: The redirection works with the HTML tag: . +# See: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#http-equiv +# +# NOTE: This page is a simplified version of the Doxygen-generated ones. +# It does use the current stylesheets, but it may break if the theme is updated. +# Ideally, we would just let Doxygen generate them, but I (Wismill) could not +# find a way to do this with the redirection feature. +REDIRECTION_PAGE_TEMPLATE = Template( + """ + +
+ + + + +This page has been moved.
++ If you are not redirected automatically, + follow the link to the current page. +
+