docs: trim dead config knobs and clarify the griffelib dependency

build_config's --site-dir/--output flags had no callers and contradicted
the fixed site/ output contract; nav validation now skips external URLs,
which are valid nav entries. The griffelib comment preempts the
reasonable suspicion that the name is a typo for griffe.

Author: maxisbey

pyproject.toml

@@ -92,6 +92,9 @@ docs = [
     "mkdocstrings-python>=2.0.5",
     # scripts/docs/build_config.py and llms_txt.py read mkdocs.yml directly.
     "pyyaml>=6.0.2",
+    # gen_ref_pages.py imports griffe directly. griffelib is not a typo: it is
+    # griffe's successor distribution (same author) and still imports as
+    # `griffe`; the old `griffe` distribution is the incompatible 1.x line.
     "griffelib>=2.1.0",
 ]
 codegen = ["datamodel-code-generator==0.57.0"]

scripts/docs/build_config.py

@@ -1,18 +1,17 @@
-"""Produce the concrete Zensical build config from ``mkdocs.yml``.
+"""Produce the concrete Zensical build config from `mkdocs.yml`.
 
-Zensical builds from ``mkdocs.yml`` directly, but it has no equivalent of
-``mkdocs-literate-nav``: the ``API Reference`` navigation has to be materialised
-as explicit entries. This script regenerates the ``docs/api/`` tree (via
-:mod:`gen_ref_pages`) and writes ``mkdocs.gen.yml`` with the real API nav
-spliced in — that generated file is what ``zensical build``/``serve`` consumes.
+Zensical builds from `mkdocs.yml` directly, but it has no equivalent of
+mkdocs-literate-nav: the "API Reference" navigation has to be materialised
+as explicit entries. This script regenerates the `docs/api/` tree (via
+gen_ref_pages) and writes `mkdocs.gen.yml` with the real API nav spliced
+in — that generated file is what `zensical build`/`serve` consumes.
 
 Usage:
-    python scripts/docs/build_config.py [--site-dir DIR] [--output FILE]
+    python scripts/docs/build_config.py
 """
 
 from __future__ import annotations
 
-import argparse
 from pathlib import Path
 
 # Both scripts live in this directory, which Python puts on sys.path[0] when
@@ -36,12 +35,12 @@ def _missing_nav_pages(nav: list, docs_dir: Path) -> list[str]:
         value = next(iter(entry.values())) if isinstance(entry, dict) else entry
         if isinstance(value, list):
             missing.extend(_missing_nav_pages(value, docs_dir))
-        elif not (docs_dir / value).is_file():
+        elif "://" not in value and not (docs_dir / value).is_file():
             missing.append(value)
     return missing
 
 
-def build_config(output: Path, site_dir: str | None = None) -> None:
+def build_config() -> None:
     config = yaml.safe_load((ROOT / "mkdocs.yml").read_text(encoding="utf-8"))
 
     api_nav = gen_ref_pages.generate()
@@ -57,19 +56,9 @@ def build_config(output: Path, site_dir: str | None = None) -> None:
     if missing := _missing_nav_pages(config["nav"], ROOT / "docs"):
         raise SystemExit(f"build_config: nav references pages that don't exist under docs/: {missing}")
 
-    if site_dir is not None:
-        config["site_dir"] = site_dir
-
+    output = ROOT / "mkdocs.gen.yml"
     output.write_text(yaml.safe_dump(config, sort_keys=False, allow_unicode=True), encoding="utf-8")
 
 
-def main() -> None:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--site-dir", default=None, help="Override the build output directory.")
-    parser.add_argument("--output", default=str(ROOT / "mkdocs.gen.yml"), help="Where to write the generated config.")
-    args = parser.parse_args()
-    build_config(Path(args.output), args.site_dir)
-
-
 if __name__ == "__main__":
-    main()
+    build_config()