doc: Fix cool URIs

doc/cool-uris.yaml

@@ -2,11 +2,14 @@
 #          Do not edit manually.
 annotated.html: []
 classes.html: []
+debugging.html: []
 deprecated.html: []
 dir_63ce773eee1f9b680e6e312b48cc99ca.html: []
 dir_891596f32582d3133e8915e72908625f.html: []
 dir_d44c64559bbebec7f509842c48db8b23.html: []
 dir_e68e8157741866f444e17edd764ebbae.html: []
+# TODO: wait for Doxygen upgrade
+# doxygen_crawl.html: []
 error-index.html: []
 files.html: []
 functions.html: []
@@ -33,8 +36,10 @@ group__x11.html: []
 index.html: []
 keymap-text-format-v1.html:
 - md_doc_keymap_format_text_v1.html
-md_doc_quick_guide.html: []
-modules.html: []
+md_doc_2quick-guide.html:
+- md_doc_quick_guide.html
+# TODO: wait for Doxygen upgrade
+# meson_options.html: []
 pages.html: []
 rule-file-format.html:
 - md_doc_rules_format.html
@@ -54,6 +59,8 @@ structxkb__keymap.html: []
 structxkb__rule__names.html: []
 structxkb__state.html: []
 todo.html: []
+topics.html:
+- modules.html
 user-configuration.html:
 - md_doc_user_configuration.html
 xkb-intro.html: []

scripts/ensure-stable-doc-urls.py

@@ -28,6 +28,7 @@ class ExitCode(IntFlag):
     NORMAL = 0
     INVALID_UPDATES = 1 << 4
     MISSING_UPDATES = 1 << 5
+    NON_UNIQUE_DIRECTIONS = 1 << 6
 
 
 THIS_SCRIPT_PATH = Path(__file__)
@@ -95,21 +96,28 @@ def update_registry(registry_path: Path, doc_dir: Path, updates: Sequence[str]):
     """
     # Parse updates
     updates_ = dict(map(parse_page_update, updates))
+    # Update
+    invalid_updates = set(updates_)
     # Load previous registry
     with registry_path.open("rt", encoding="utf-8") as fd:
-        registry = yaml.safe_load(fd) or {}
+        registry: dict[str, list[str]] = yaml.safe_load(fd) or {}
     # Expected updates
     missing_updates = set(file for file in registry if not (doc_dir / file).is_file())
-    # Update
-    invalid_updates = set(updates_)
+    # Ensure each page is unique
+    for d, rs in registry.items():
+        if clashes := frozenset(rs).intersection(registry):
+            print(
+                f"[ERROR] The following redirections of “{d}”",
+                f"clash with canonical directions: {clashes}",
+            )
+            exit(ExitCode.NON_UNIQUE_DIRECTIONS)
     redirections = frozenset(chain(*registry.values()))
     for file in glob.iglob("**/*.html", root_dir=doc_dir, recursive=True):
         # Skip redirection pages
         if file in redirections:
             continue
         # Get previous entry and potential update
-        old = updates_.get(file)
-        if old:
+        if old := updates_.get(file):
             # Update old entry
             invalid_updates.remove(file)
             entry = registry.get(old)
@@ -137,8 +145,13 @@ def update_registry(registry_path: Path, doc_dir: Path, updates: Sequence[str]):
         exit_code |= ExitCode.INVALID_UPDATES
     if missing_updates:
         for old in missing_updates:
-            print(f"[ERROR] “{old}” not found and has no update.")
-        exit_code |= ExitCode.MISSING_UPDATES
+            # Handle older Doxygen version
+            if old in redirections:
+                missing_updates.remove(old)
+            else:
+                print(f"[ERROR] “{old}” not found and has no update.")
+        if missing_updates:
+            exit_code |= ExitCode.MISSING_UPDATES
     if exit_code:
         print("[ERROR] Processing interrupted: please fix the errors above.")
         exit(exit_code.value)