From 0b747d99cfa2f75698da3626f71aea484b524ac0 Mon Sep 17 00:00:00 2001 From: John Travers Date: Wed, 4 Nov 2026 20:28:11 +0000 Subject: [PATCH 1/6] Docs: keep the source record pages out of the navigation tree Sphinx copies the whole navigation tree for every page it writes, and the theme's sidebar asks for it on nearly every page. With 763 source records in a hidden toctree that took 177 s of a 271 s profiled build (about 35 million node copies), most of the build's time and most of its length on Read the Docs. The record pages are now orphans, reached through the alphabetical index. Their URLs and search entries stay. They lose the sidebar and previous and next links. The local build without the gallery goes from 164 s to 39 s. The setting in conf.py that narrowed the record pages' sidebar goes with them. Co-Authored-By: Claude Opus 5.5 --- changelog.d/docs-navigation.fixed.md | 1 + docs/_ext/source_catalogue.py | 9 ++++++--- docs/conf.py | 4 ---- docs/developers/documentation.md | 5 +++++ tests/test_source_catalogue.py | 6 +++++- 5 files changed, 17 insertions(+), 8 deletions(-) create mode 100644 changelog.d/docs-navigation.fixed.md 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) From d2988a5e6812bd538c4bec61ec4a7b27754cec17 Mon Sep 17 00:00:00 2001 From: John Travers Date: Wed, 4 Nov 2026 20:34:39 +0000 Subject: [PATCH 2/6] Repeat build 1 of the docs navigation fix [skip ci] From 5148912434b56314cba78647b8ba97ec18dfea20 Mon Sep 17 00:00:00 2001 From: John Travers Date: Wed, 4 Nov 2026 20:40:01 +0000 Subject: [PATCH 3/6] Repeat build 2 of the docs navigation fix [skip ci] From 495738b8b5839be8591a829364fad9df04ea0fc6 Mon Sep 17 00:00:00 2001 From: John Travers Date: Wed, 4 Nov 2026 20:44:35 +0000 Subject: [PATCH 4/6] Repeat build 3 of the docs navigation fix [skip ci] From 3727b72f282fee2febc82e25910669c896fe51ec Mon Sep 17 00:00:00 2001 From: John Travers Date: Wed, 4 Nov 2026 20:49:09 +0000 Subject: [PATCH 5/6] Repeat build 4 of the docs navigation fix [skip ci] From f24b5537ebee9d93ba74697556e914c199ec4b47 Mon Sep 17 00:00:00 2001 From: John Travers Date: Wed, 4 Nov 2026 20:53:43 +0000 Subject: [PATCH 6/6] Repeat build 5 of the docs navigation fix [skip ci]