diff --git a/changelog.d/docs-navigation.fixed.md b/changelog.d/docs-navigation.fixed.md new file mode 100644 index 0000000..58ed98f --- /dev/null +++ b/changelog.d/docs-navigation.fixed.md @@ -0,0 +1 @@ +The manual builds in about a third of the time: source record pages are no longer in the navigation tree. They keep their URLs and stay in search, and are reached through the alphabetical source index, so they no longer have a sidebar or previous and next links. No recommended value moved. diff --git a/docs/_ext/source_catalogue.py b/docs/_ext/source_catalogue.py index c12a50d..3b5730c 100644 --- a/docs/_ext/source_catalogue.py +++ b/docs/_ext/source_catalogue.py @@ -43,6 +43,9 @@ def render_record(source_id: str, record: dict[str, Any]) -> str: quantities = sorted({d["quantity"] for d in datasets}) title = source_id parts = [ + # Reached through the alphabetical index, not the navigation tree: see + # generate_catalogue. + ":orphan:", title + "\n" + "=" * len(title), _paragraph(record["citation"]), f"`Source record <{RECORD_URL}{quote(source_id)}.toml>`__ ยท " @@ -154,9 +157,9 @@ def generate_catalogue(records_dir: Path, output_dir: Path) -> tuple[str, ...]: ] for letter, entries in groups.items(): index.extend([letter + "\n" + "-" * len(letter), "\n\n".join(entries)]) - index.append( - ".. toctree::\n :hidden:\n\n" + "\n".join(" " + s for s in records) - ) + # The index links each record but lists none in a toctree. Sphinx copies the whole + # navigation tree for every page it writes, so several hundred records there made + # up about two thirds of the build's time. pages["index"] = "\n\n".join(index) + "\n" for name, content in pages.items(): path = output_dir / (name + ".rst") diff --git a/docs/conf.py b/docs/conf.py index 0352ec4..da0ec6c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -129,10 +129,6 @@ def _edit_page_context(_app, pagename, _templatename, context, _doctree): - # Browse individual records in the alphabetical index; keep the data chapters - # visible instead of expanding all source records in every page's sidebar. - if pagename.startswith("generated/sources/"): - context["theme_navigation_depth"] = 2 # Generated pages have no source file in GitHub to edit. if pagename.startswith( ("auto_gallery/", "api/generated/", "generated/") diff --git a/docs/developers/documentation.md b/docs/developers/documentation.md index c7d6e65..ab6d4f3 100644 --- a/docs/developers/documentation.md +++ b/docs/developers/documentation.md @@ -55,6 +55,11 @@ index and one stable page per source identifier under `docs/generated/sources/`. Those files are ignored by Git, and unchanged pages are not rewritten. Deleted source records lose their generated page at the next build. +The record pages are reached through the index and are not in any toctree. Sphinx +copies the whole navigation tree for every page it writes, so listing them there, even +hidden, took about two thirds of the build's time. A new kind of page generated in the +hundreds should stay out of the tree in the same way. + Edit the source record to correct its metadata, following the data and register rules. Do not edit the generated catalogue. Notes, formula-only and notes-only records, missing DOIs, Unicode and punctuation are supported without a second diff --git a/tests/test_source_catalogue.py b/tests/test_source_catalogue.py index cdebb35..d148405 100644 --- a/tests/test_source_catalogue.py +++ b/tests/test_source_catalogue.py @@ -30,9 +30,13 @@ def test_every_source_and_entry_appears_once(tmp_path): assert catalogue.generate_catalogue(records_dir, tmp_path) == tuple(records) assert {p.stem for p in tmp_path.glob("*.rst")} == {*records, "index"} index = (tmp_path / "index.rst").read_text(encoding="utf-8") - assert re.findall(r"^ ([a-z0-9_]+)$", index, re.MULTILINE) == list(records) + assert re.findall(r"^:doc:`([a-z0-9_]+)`", index, re.MULTILINE) == list(records) + # Records stay out of the navigation tree, which Sphinx copies for every page + # it writes: there they took about two thirds of the build's time. + assert "toctree" not in index for source_id, record in records.items(): page = (tmp_path / f"{source_id}.rst").read_text(encoding="utf-8") + assert page.startswith(":orphan:\n") # These blocks retain structured metadata exactly, including corrections; # code blocks do not reinterpret punctuation as Markdown or mathematics. blocks = re.findall(r"\.\. code-block:: text\n\n((?: .*\n?)+)", page)