docs(sphinx): caption the root toctrees, point the edit button at main (#719, #969)

[JarryShaw]

• Searched for similar pull requests
• Followed the coding style (make pylint, make mypy, make isort) — those targets cover pcapkit/, util/ and examples/generators/; no file in them changed
• make test passes, and a test case covers the change — ran the tests/project toctree-parsing modules only (91 tests, no failures); the full suite is not runnable here
• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible — N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• chore — anything else

---

Description of your pull request and other information

Closes #969, and takes items 1 and 2 of the #719 navigation ruling.

toc_object_entries: measured, and the recommendation is to leave it False. Two full
HTML builds, True against False: the page-local drawer goes 5 → 12,960 entries on
pcapkit/const/reg, 6 → 1,233 on protocols/internet/mh (estimated at 308 — autodoc
members nest five levels deep), 43 → 513 on const/mh, and 729 → 22,261 tree-wide,
for 109s → 1,052s of build time. 120 of the 188 pages stay under 20 entries either way, so
True dumps thousands onto precisely the pages already hardest to read. Capping the depth
does not rescue it: the drawer's depth is a per-document :tocdepth: field rather than a
conf.py option, and the only depth still navigable on mh is 2 — which excludes every
object entry, i.e. is what False already gives. The measurement is now recorded against
the setting, so it is not re-opened blind.

Captions. Also measured first: only a root-document toctree's caption reaches furo's
global sidebar; a nested one renders on its own page only, and on a :hidden: toctree it
renders nowhere. So index.rst's three are captioned — API Reference / Guides & Changelog /
Contributing — plus pcapkit/index.rst (Subpackages, the one nested case that is not a
restatement of its page title). The other 31 stay bare: const/index.rst and
vendor/index.rst already carry a section heading above each toctree, and the
single-toctree package pages would only restate their own title.

#969 is the one-liner — source_branch master → main, so the "Edit this page" button
stops targeting a branch that does not exist. Verified in the built HTML.

The full build succeeds with 61 warnings, the same set as unmodified main.
docs/source/contributing/ is untouched — its caption belongs to #971's follow-up.

[JarryShaw]

The red mark here is an infrastructure stall, not this diff. Root-caused rather
than reported.

Required checks passed failed because engine-tests reported cancelled, and that
because Engines Python 3.10 (PCAP_CT) was killed at the timeout-minutes: 30 on
unit-tests.yml:327 while still inside apt-get update:

15:58:06-ish  Get:… archive.ubuntu.com … InRelease
+29m52s       ##[error]The operation was canceled.

On the same run (36888646396) the other five PCAP_CT legs finished in 39–81
seconds. A docs change cannot affect an engine's system-package install.

Filed as #974 with the fix — apt retries and timeouts, plus a step-level cap. I am not
re-running the workflow; that is yours. The verdict on this PR stands on its content.

[JarryShaw]

NEEDS CHANGES at 259f439f5 — sonnet cross-review, round 1. It reproduced the
headline numbers exactly and then found two inaccuracies in the conf.py comment
itself. Fixed at cda32e124.

Reproduced independently, not just corroborated: mh 6 → 1,233, reg 5 →
12,960 — identical to the author's figures, measured in a minimal two-page project
with the real conf.py and the real package. The depth table too, by calling
document_toc with tocdepth overridden: depth 2 → 5, depth 3 → 505, depth 4 →
1,179. And it confirmed #969's one-liner end-to-end, rendering the edit button both
ways: .../edit/master/... before, .../edit/main/... after.

Two claims in the comment were wrong, and a comment that enshrines a wrong claim is
worse than none:

• "the only depth still navigable on mh is 2, which excludes every object entry and
  is therefore what False already gives." Wrong twice. At depth 2 the page's own
  top-level class survives, and — I verified this from the build's doctree cache —
  depth 2 drops two genuine headings, Type Stubs and Auxiliary Functions, that
  False shows. So capping is worse than False, not equal to it. The conclusion
  survives; the reasoning given for it did not.
• "rather than any option here." rst_prolog prepends to every document
  (sphinx/parsers.py:104, util/rst.py:80-99), so :tocdepth: can be defaulted
  tree-wide from conf.py. "Touching 185 documents" overstated the alternative.

Both corrected. Neither changes the decision to keep False.

Still UNVERIFIED by either of us at full scale: the tree-wide 729 → 22,261, the
"120 of 188 pages under 20", and the exact 109s/1,052s timings. A controlled
two-page benchmark put True 39s slower with no cache reuse on either side, which
supports the direction. Also confirmed: baseline and PR both build 61 warnings,
normalised sets identical — zero new warnings.

[JarryShaw]

GOOD TO GO at cda32e124 — sonnet cross-review, round 2 clean.

Verified on my side: the diff between the two heads is one file, one hunk,
+10/−5, and no non-comment line changed at all — toc_object_entries = False
itself is untouched. All four of the old phrases are gone from the file: zero hits
each for excludes every object entry, already gives, rather than any option,
185 document.

Round 2 confirmed the corrected text against the numbers it had measured in round 1
rather than against my description of them — depth 2 under True gave
[MH - Mobility Header, MH, Auxiliary Data, Header Schemas, Data Models], so the
class does survive and Type Stubs/Auxiliary Functions are exactly the two drops.
And rst_prolog = ':tocdepth: 2\n' really did produce
env.metadata[docname] == {'tocdepth': 2} for every page untouched. Max added line
length 83, the file's 10 pre-existing over-88 lines unchanged, py_compile clean,
and a single-page real build succeeding on the new conf.py.

Three figures stay unverified by either of us, stated rather than implied: the
tree-wide 729 → 22,261, the "120 of 188 pages under 20", and the exact 109s/1,052s.
Everything load-bearing for the decision — the two per-page counts and the whole
depth table — was reproduced exactly and independently.

Not merge-ready yet: the red marks here are #974's apt-get stall, not this diff.