Re-add toc navigation #682

bmunkholm · 2026-01-08T08:27:59Z

Summary of the changes / Why this is an improvement

Adding TOC expand-collapse icons again (as #664 was reverted).

This is a variant of #681 that just includes the navigation icons and avoids removing the sass build warnings.

Preview

https://crate-docs-theme--682.org.readthedocs.build/en/682/

amotl

Thank you for submitting a patch without the Sass updates, so we can focus on the subject matter itself.

NB: This patch lacks a changelog item in CHANGES.rst, what the previous one had. In there, don't hesitate to be more explicit about mentioning the migration of the primary navigation representation from HTML/Jinja to Python, e.g. like a compressed version of "Use a / Switched to a built-in Sphinx extension to define the primary navigation instead of an HTML/Jinja template construct", instead of dismissing this significant change as just "advanced navigation". Thanks!

docs/tests/section1/subpage1.rst

amotl · 2026-01-08T09:13:00Z

src/crate/theme/rtd/__init__.py

+def setup(app):
+    """
+    Registers event handlers to setup navigation.
+    """
+    app.connect("html-page-context", _add_crate_navigation)
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }


The theme has a def setup entrypoint already. Is your intention to introduce another one, to be able to slot in those features on behalf of a dedicated Sphinx extension?

In this case, please don't twist hierarchies, and move this def setup downwards towards the extension itself, not above the main def setup entrypoint of the whole theme, located in conf/__init__.py.

Long story short, please move all initializer code into sidebartoc.py itself, so it can become a self-contained Sphinx extension like possibly intended.

The code was written "last year"... Not sure why I had the "extension" part there still. I've cleanup the setup parts a bit now.

src/crate/theme/rtd/conf/__init__.py

amotl

Thanks for the streamlining. I am acknowledging now.

Next time, please don't forget to re-request a review,

otherwise there is the danger about waiting for ages, because I don't get any notification about it, and the item is also not included on the canonical page where to review requested reviews [sic].

-- https://github.com/pulls/review-requested

…ate-docs-theme into new-toc-navigation-pure

bmunkholm · 2026-01-08T11:22:49Z

Next time, please don't forget to re-request a review,
That for the reminder - I sure will. In this case I was actually just waiting until I had added the changes.rst update so you could review that as well :-) 🙇

amotl · 2026-01-08T11:34:31Z

CHANGES.rst

+- (re)Added TOC expand/collapse icons and more advanced navigation. The expanded
+  or collapsed state of individual TOC entries is now persisted and you can
+  therefore keep multiple sections expanded at the same time while navigating
+  pages. A sideeffect is that the TOC state is now also persisted across page
+  reloads.
+  Not mentioned previously, it also introduce a significant change to how the
+  sidebartoc is defined. Previously it was defined in HTML/Jinja templates,
+  now it is generated in Python code.
+  This was first introduced in 0.43.0, but reverted in 0.44.0.


Can you phrase this less of a story, i.e. more concise? /cc @coderabbitai

amotl · 2026-01-08T11:36:55Z

CHANGES.rst

+- (re)Added TOC expand/collapse icons and more advanced navigation. The expanded
+  or collapsed state of individual TOC entries is now persisted and you can
+  therefore keep multiple sections expanded at the same time while navigating
+  pages. A sideeffect is that the TOC state is now also persisted across page
+  reloads.


"Persisted" is used twice. This whole paragraph can be phrased more concise.

yeah - what a wordy mess :-).

Copilot

Pull request overview

This PR re-adds TOC expand/collapse navigation icons that were previously reverted in version 0.44.0. The implementation migrates from Jinja2 template-based navigation generation to a Python-based approach using a new sidebartoc.py module, which enables integration with Furo's navigation enhancer for collapsible icons and checkboxes. The navigation state is now persisted across page loads using localStorage.

Key changes:

New Python module sidebartoc.py generates navigation HTML and processes it through Furo's navigation enhancer
JavaScript added for navigation state persistence and expand/collapse behavior
CSS/SCSS styling for Furo-compatible collapsible navigation
Template simplification with navigation generation moved from Jinja to Python

Reviewed changes

Copilot reviewed 21 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/crate/theme/rtd/sidebartoc.py	New Python module that generates multi-project navigation HTML and enhances it with Furo's navigation tree for collapsible icons
src/crate/theme/rtd/crate/static/js/custom.js	Added navigation state persistence logic using localStorage and click handlers for expand/collapse behavior
src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss	New SCSS file with styling for Furo-compatible collapsible navigation elements
src/crate/theme/rtd/crate/static/css/index.css	Adds import for new furo-collapsible-toc.scss file
src/crate/theme/rtd/crate/static/css/crateio-rtd.css	Removes old CSS rules for TOC display that are now handled by Furo's navigation enhancer
src/crate/theme/rtd/crate/sidebartoc.html	Simplified to just render the enhanced navigation from context variable
src/crate/theme/rtd/crate/sidebar.html	Added 'sidebar-tree' class to nav element for CSS targeting
src/crate/theme/rtd/conf/init.py	Registers the new Sphinx event handler for navigation enhancement and adds comment about SCSS bundling
src/crate/theme/rtd/init.py	Refactored utility functions to eliminate redundant `current_dir` variable shadowing
docs/tests/*.rst	New test documentation pages for verifying navigation behavior
docs/index.rst	Reordered toctree entries and added tests/index
CHANGES.rst	Documents the re-addition of TOC expand/collapse icons
.gitignore	Adds pattern to ignore underscore-prefixed files

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/crate/theme/rtd/crate/static/js/custom.js

src/crate/theme/rtd/crate/static/css/index.css

src/crate/theme/rtd/sidebartoc.py

amotl · 2026-01-08T12:42:36Z

Do you know why Copilot is now active here, but @coderabbitai does not respond any longer?
Edit: Well, maybe it hasn't been activated on this repository yet?

bmunkholm · 2026-01-08T12:45:07Z

I don't know why coderabbit isn't responding. But I manually summoned Copilot by requesting it as reviewer in the absense of the rabbit.
Perhaps this repo hasn't been added in the config for coderabbit?

cherrypick: Add TOC expand-collapse icons (#664)

371595e

bmunkholm mentioned this pull request Jan 8, 2026

Re-add toc navigation #681

Draft

bmunkholm requested a review from amotl January 8, 2026 09:19

amotl requested changes Jan 8, 2026

View reviewed changes

bmunkholm added 2 commits January 8, 2026 11:52

simplified setup

9096b33

Merge branch 'main' into new-toc-navigation-pure

3c0bb90

amotl approved these changes Jan 8, 2026

View reviewed changes

bmunkholm added 2 commits January 8, 2026 12:20

update release notes

f381eb3

Merge branch 'new-toc-navigation-pure' of https://github.com/crate/cr…

c178db8

…ate-docs-theme into new-toc-navigation-pure

bmunkholm requested a review from amotl January 8, 2026 11:22

amotl reviewed Jan 8, 2026

View reviewed changes

make release notes more concise

98b70f7

bmunkholm requested review from amotl and Copilot January 8, 2026 12:35

Copilot started reviewing on behalf of bmunkholm January 8, 2026 12:37 View session

Copilot AI reviewed Jan 8, 2026

View reviewed changes

src/crate/theme/rtd/crate/static/js/custom.js Outdated Show resolved Hide resolved

src/crate/theme/rtd/crate/static/css/index.css Show resolved Hide resolved

src/crate/theme/rtd/sidebartoc.py Show resolved Hide resolved

amotl approved these changes Jan 8, 2026

View reviewed changes

feedback updates

0d5e546

bmunkholm merged commit f3a1722 into main Jan 8, 2026
8 checks passed

bmunkholm deleted the new-toc-navigation-pure branch January 8, 2026 13:07

Re-add toc navigation #682

Re-add toc navigation #682

Uh oh!

Conversation

bmunkholm commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of the changes / Why this is an improvement

Preview

Uh oh!

amotl left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

amotl Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amotl Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

bmunkholm Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

amotl left a comment

Choose a reason for hiding this comment

Uh oh!

bmunkholm commented Jan 8, 2026

Uh oh!

amotl Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

amotl Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

bmunkholm Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amotl commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bmunkholm commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bmunkholm commented Jan 8, 2026 •

edited

Loading

amotl left a comment •

edited

Loading

amotl Jan 8, 2026 •

edited

Loading

amotl commented Jan 8, 2026 •

edited

Loading

bmunkholm commented Jan 8, 2026 •

edited

Loading