From 0b747d99cfa2f75698da3626f71aea484b524ac0 Mon Sep 17 00:00:00 2001 From: John Travers Date: Wed, 4 Nov 2026 20:28:11 +0000 Subject: [PATCH 1/2] 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 00000000..58ed98f9 --- /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 c12a50dc..3b5730cf 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 0352ec47..da0ec6cf 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 c7d6e652..ab6d4f35 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 cdebb356..d1484057 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 24d448407a1f71f60a6fa0f6127a6c4adc96d6e0 Mon Sep 17 00:00:00 2001 From: John Travers Date: Wed, 4 Nov 2026 20:59:27 +0000 Subject: [PATCH 2/2] Changelog: state the build's measured saving Six builds on Read the Docs took 230 to 341 s, against about 600 s before. Co-Authored-By: Claude Opus 5.5 --- changelog.d/docs-navigation.fixed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog.d/docs-navigation.fixed.md b/changelog.d/docs-navigation.fixed.md index 58ed98f9..38dd42e7 100644 --- a/changelog.d/docs-navigation.fixed.md +++ b/changelog.d/docs-navigation.fixed.md @@ -1 +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. +The manual builds in less than half 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.