docs: group the sidebar with toctree captions - #100
Merged
Conversation
The sidebar listed every page under three broad toctrees with no group headers, so the nav read as one long list and the topics were not visible at a glance. Give each toctree a `:caption:`, which the Read the Docs theme renders as a section header in the sidebar, following the same layout the Picklock docs use. The captions are now the only grouping, so the intermediate hub page between a caption and the content no longer earns its place: a caption "User's Guide" led to a page "User Guide" whose body was a "What's covered" restatement of the toctree. Delete `docs/guide/index.md` and list the guide's leaf pages directly under the root captions, retargeting its two inbound links at `guide/opening-process.md`. Split the API reference toctree into three captioned groups as well, and drop the vague "Advanced" caption in favour of "Memory Allocation". Also fix a stale comment in the Makefile that still named Furo as the docs theme; it has been sphinx_rtd_theme since the migration.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #100 +/- ##
==========================================
- Coverage 89.92% 89.89% -0.03%
==========================================
Files 41 41
Lines 3682 3682
==========================================
- Hits 3311 3310 -1
- Misses 371 372 +1
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
JeanExtreme002
added a commit
that referenced
this pull request
Sep 12, 2026
Patch, because everything that landed since v3.0.0 is documentation: #100 regrouped the Sphinx sidebar with toctree captions. No library code changed, so no caller can observe the difference. The bump is what Read the Docs needs. It serves `/en/stable/` from the highest semver tag, which is still v3.0.0 — the commit before the docs change — so `stable` keeps showing the old navigation even though `/en/latest/` already rebuilt from main. Tagging v3.0.1 moves `stable` onto the current docs. Also refresh the fallback `release` in `docs/conf.py`, which had been pinned at 2.0.0. It is only read when the package cannot be imported at build time, so it has never affected a Read the Docs build, but it should not drift either.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The docs sidebar listed every page under three broad toctrees (
User's Guide,API Reference,Additional Notes) with no group headers, so the nav read as one long undifferentiated list — you could not see the topics at a glance.What changed
Every
{toctree}now carries a:caption:, which the Read the Docs theme renders as a section header in the sidebar. This follows the layout the sibling Picklock docs already use.The sidebar now reads:
Three follow-on changes fall out of that:
docs/guide/index.mdis deleted. Once the captions carry the grouping, the hub page stops earning its place: a caption "User's Guide" led to a page titled "User Guide" whose body was a "What's covered" restatement of the toctree — three labels before the reader reached any content. The guide's leaf pages are now listed directly under the root captions. Its two inbound links (docs/index.md,docs/api/index.md) point atguide/opening-process.mdinstead.The Entry Point,Objects You Get BackandErrors and Helpers.Advancedis renamedMemory Allocation— a concrete label beats a vague one, even for a single-page group.Also fixes a stale comment in
Makefilethat still named Furo as the docs theme; it has beensphinx_rtd_themesince the migration.Verification
python -m sphinx -b html docsbuilds clean — no warnings.#anchoracrossdocs/andREADME.mdresolves.