Repository navigation
docs(sphinx): hide the three root toctrees from the page body - #975
Conversation
- 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.
|
GOOD TO GO at It ran the check that actually settles the risk, which neither the author nor I had: Also stronger than the original claim: the Two things it added that make the case better than "cheapest fix":
It also found an unstated side effect, which I have added to the PR body: Nothing |
Please follow the guide below
make pylint,make mypy,make isort)make testpasses, and a test case covers the changedocs/source/changelog/— N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657What is the purpose of your pull request?
docs— documentation onlyDescription 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 #719ruling 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.htmlandpcapkit/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 nothingthere. The page already lists
About,Module Structure,Engine Comparison,Installation,Indices and tables, so the sidebar is thesingle 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) derivesog:descriptionandmeta name="description"from thestart of the page body, so the landing page's social and search description was
picking up the nav captions:
It now describes actual content. That is the only change outside the toctree
region, so a reviewer diffing the HTML will see it.