Skip to content

docs(sphinx): hide the three root toctrees from the page body - #975

Merged
JarryShaw merged 1 commit into
mainfrom
docs/973-hide-root-toctrees
Oct 1, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
docs/973-hide-root-toctrees

Conversation

@JarryShaw

@JarryShaw JarryShaw commented Oct 1, 2026 •

Copy link
Copy Markdown
Owner

Please follow the guide below

What is the purpose of your pull request?

  • docs — documentation only

Description of your pull request and other information

Fixes #973. index.rst's three toctrees rendered twice on the root page only
(furo sidebar + inline body); #972's captions just made the pre-existing
duplication visible. Adds :hidden: to all three, per the owner's #719
ruling to avoid duplicated information.

Caption counts in index.html: "API Reference" / "Guides & Changelog" /
"Contributing" each go 2 → 1, survivor in sidebar-tree.

Sidebar unaffected: all three captions and every entry under them still
render on index.html, pcapkit/index.html and pcapkit/const/mh.html.

What the root page loses: the inline contents list between the intro and
About — a reader scrolling rather than using the sidebar now sees nothing
there. The page already lists About, Module Structure, Engine Comparison, Installation, Indices and tables, so the sidebar is the
single remaining index.

Warnings: build succeeded, 61 warnings before and after — identical sets.

One side effect worth naming, found in review. sphinxext.opengraph
(conf.py:77) derives og:description and meta name="description" from the
start of the page body, so the landing page's social and search description was
picking up the nav captions:

before: ...analysis library. API Refe...
after:  ...analysis library. About: P...

It now describes actual content. That is the only change outside the toctree
region, so a reviewer diffing the HTML will see it.

- Each of index.rst's three toctrees rendered twice on the root page only:
  once in furo's sidebar, once again inline in the page body. Add :hidden:
  to all three so the captioned sidebar is the single index.
- Verified: "API Reference", "Guides & Changelog", "Contributing" each go
  from 2 occurrences in index.html to 1, the survivor inside sidebar-tree.
  Sidebar entries are unchanged on index.html, pcapkit/index.html and
  pcapkit/const/mh.html; :ref:-based "Indices and tables" is unaffected.
- Build succeeded, 61 warnings both before and after, identical warning
  sets once paths are normalised.

Build: sphinx-build -b html, build succeeded, 61 warnings (matches main).
Tests: tests/project/test_conventions_doc_claims,
test_sentinels_doc_page_934_unit, test_changelog_md via plain unittest --
91 tests, 1 skip, 0 failures.
@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Oct 1, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

GOOD TO GO at 9d1ab9652 — opus cross-review, first round clean. Different
model from the author (sonnet).

It ran the check that actually settles the risk, which neither the author nor I had:
diff -rq across the two full built trees reports exactly two differing files —
index.html and _sources/index.rst.txt. Every other page in the 188-page site is
byte-identical. The site-wide navigation gutting a mis-applied :hidden: could have
caused did not happen, and that is proof rather than inference.

Also stronger than the original claim: the sidebar-tree block on index.html,
pcapkit/index.html and pcapkit/const/mh.html carries 206 hrefs before and 206
after, byte-for-byte identical and in the same order
. Caption occurrences 6 → 3
whole-page, survivors inside sidebar-tree; the three toctree-wrapper compound
divs persist with inner content of length exactly 0, so they are emptied rather than
removed. 61 warnings both ways, Counter equality on the normalised multisets.

Two things it added that make the case better than "cheapest fix":

  • index.rst:18-20 holds an already-commented-out .. contents:: :depth: 2 :local: — so an inline landing-page index was deliberately disabled at some point,
    and a toctree was never the chosen mechanism for one. I verified those lines.
  • At :maxdepth: 1 the body copy listed nine flat links identical to the sidebar's
    top level, directly above four real content sections. It was duplication without
    being a useful index.

It also found an unstated side effect, which I have added to the PR body:
sphinxext.opengraph (conf.py:77) was deriving the landing page's
og:description from the nav captions — ...library. API Refe... before,
...library. About: P... after. The only change outside the toctree region.

Nothing UNVERIFIED. Ran 91 tests ... OK (skipped=1) under plain unittest, and
it established why no parser is affected rather than only that none failed.

@JarryShaw JarryShaw added review: good-to-go Cross-review at the current head says ready; CI state is separate and removed review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Oct 1, 2026
@JarryShaw
JarryShaw merged commit 12b9449 into main Oct 1, 2026
63 checks passed
@JarryShaw
JarryShaw deleted the docs/973-hide-root-toctrees branch October 1, 2026 17:57
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 1, 2026
@JarryShaw JarryShaw added this to the 1.5 milestone Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Pull requests that change documentation only (docs: subject prefix)

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

docs: the root page renders each toctree twice, in the sidebar and inline

1 participant