TOC expand-collapse icons - take 2

[bmunkholm]

Summary of the changes / Why this is an improvement

Added icons for collapsable/expandable TOC sections.
It makes it easier to see which sections can be expanded when browsing for what might be relevant.

Compared to #659 this:

• is reusing more of Furos navigation
• moves the TOC entry definition from html to python.
• adds feature to preserve collapse/expand state for individual sections. (i.e. you can have multiple sections expanded while clicking different pages as they no longer auto collapse when changing page)
• has a background shade when hovering the cursor over toc entries

Review individual commits as quite a few changes is adding some more docs test pages.

Preview

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

[Copilot]

Pull request overview

This PR refactors the table of contents (TOC) navigation to add expand/collapse icons and state persistence. The main improvement is moving TOC generation from Jinja2 templates to Python code, enabling integration with Furo's navigation enhancer system to provide collapsible sections with visual indicators.

• Migrates navigation HTML generation from sidebartoc.html template to new sidebartoc.py Python module
• Integrates Furo's navigation tree processor to add expand/collapse icons and checkboxes
• Implements localStorage-based state persistence for navigation expand/collapse across page navigation
• Adds custom SCSS styling to match CrateDB theme while using Furo's collapsible navigation components

Reviewed changes

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

Show a summary per file

File	Description
src/crate/theme/rtd/sidebartoc.py	New module that generates multi-project navigation HTML structure programmatically
src/crate/theme/rtd/__init__.py	Adds Sphinx extension setup with html-page-context event handler to integrate Furo navigation
src/crate/theme/rtd/crate/static/js/custom.js	Implements localStorage-based navigation state persistence and click handlers for expand/collapse
src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss	Custom SCSS to style Furo's collapsible navigation to match CrateDB theme
src/crate/theme/rtd/crate/static/css/index.css	Imports new SCSS file for collapsible TOC
src/crate/theme/rtd/crate/static/css/crateio-rtd.css	Removes old TOC display rules now handled by Furo
src/crate/theme/rtd/crate/sidebartoc.html	Simplified to single line template that renders Python-generated navigation
src/crate/theme/rtd/crate/sidebar.html	Adds sidebar-tree class to enable Furo navigation styling
src/crate/theme/rtd/conf/__init__.py	Registers CrateDB theme extension for Furo integration
docs/tests/**	Adds test pages for verifying navigation behavior
docs/index.rst	Reorders entries to include new test pages
.gitignore	Adds pattern to ignore underscore-prefixed files/directories

---

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

[bmunkholm]

@amotl Was it something like this you had in mind?
This has some better features I think for the independant expand/collapse of individual sections.
Which do you prefer? Personally I think this one is better.

[amotl]

@amotl Was it something like this you had in mind? This has some better features I think for the independant expand/collapse of individual sections. Which do you prefer? Personally I think this one is better.

Absolutely. If the idea works out well, and if you need the flexibility, I think composing the primary navigation through a DSL is more efficient than doing it using Jinja templates like before, similarly like GH-405 was aiming at ¹. Using Python as DSL is the most flexible representation, so it gave you the power of conditionals and loops, which I see you've enjoyed already.

By connecting this with the great Furo navigation mechanics, if you also like the Python-based representation better than the previous one, and the Furo-enhanced HTML rendering, I think it's an excellent start into this direction to leverage the best of both worlds, so let's merge and ship it, if it also satisfies your needs for better composability?

Footnotes

1. My other exercises aimed at a more high-level Python API so you don't need to shuffle any HTML any longer, and possibly a Sphinx directive on top of this API, which works similar like toctree, but that's just dreaming, and will probably need to sacrifice in flexibility again. ↩

[bmunkholm]

@amotl Thanks for the always speedy reviews 🙇 !

[mergify]

⚠️ The sha of the head commit of this PR conflicts with #667. Mergify cannot evaluate rules on this PR. ⚠️