docs: fix autorefs by using fully qualified path

docs/gen_ref_pages.py

@@ -1,36 +1,45 @@
-"""Generate the code reference pages."""
+"""Generate code reference pages for mkdocstrings.
+
+This script is executed by the mkdocs-gen-files plugin during the MkDocs build
+process. It walks the source package, creates a corresponding Markdown stub for
+each public module, and builds a nav.yml file so that the API reference section
+is generated automatically.
+"""
 
-import os
 from pathlib import Path
 
 import mkdocs_gen_files
+import yaml
 
-SRC_DIR = "pcdigitizer"
-WRITE_DIR = "api"
+SRC_DIR = Path("pcdigitizer")
+DOC_DIR = Path("api")
+SKIP_MODULES = {"__main__", "__init__"}
+SKIP_PREFIXES = ("_",)
 
-for path in sorted(Path(SRC_DIR).rglob("*.py")):  #
-    module_path = path.relative_to(SRC_DIR).with_suffix("")  #
+nav_items: list[dict[str, str] | dict[str, list]] = []
 
-    doc_path = path.relative_to(SRC_DIR).with_suffix(".md")  #
+for path in sorted(SRC_DIR.rglob("*.py")):
+    module_path = path.relative_to(SRC_DIR).with_suffix("")
+    doc_path = path.relative_to(SRC_DIR).with_suffix(".md")
+    full_doc_path = DOC_DIR / doc_path
 
-    if not os.path.exists(Path(WRITE_DIR)):
-        os.mkdir(Path(WRITE_DIR))
+    parts = tuple(module_path.parts)
 
-    full_doc_path = Path(WRITE_DIR, doc_path)  #
-
-    parts = list(module_path.parts)
-
-    if parts[-1] == "__init__":  #
-        parts = parts[:-1]
-    elif parts[-1] == "__main__":
+    if not parts:
+        continue
+    if parts[-1] in SKIP_MODULES:
+        continue
+    if any(part.startswith(prefix) for part in parts for prefix in SKIP_PREFIXES):
         continue
 
-    if len(parts) == 0:
-        continue
+    qualified_name = ".".join((SRC_DIR.name, *parts))
 
-    with mkdocs_gen_files.open(full_doc_path, "w") as fd:  #
-        identifier = ".".join(parts)  #
+    nav_items.append({qualified_name: doc_path.as_posix()})
 
-        print("::: " + identifier, file=fd)  #
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        fd.write(f"::: {qualified_name}\n")
 
-    mkdocs_gen_files.set_edit_path(full_doc_path, path)  #
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open(DOC_DIR / "nav.yml", "w") as nav_fd:
+    yaml.dump(nav_items, nav_fd, default_flow_style=False, sort_keys=False)