Not for merging: repeat Read the Docs builds of #44

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.

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")

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/")

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

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)