From 35603b8f3d1d0edc2bb5672ad5ddd393f2e50c32 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Wed, 17 Dec 2025 09:47:45 +0100 Subject: [PATCH 1/2] Add TOC expand-collapse icons - again --- .gitignore | 1 + CHANGES.rst | 1 + docs/index.rst | 12 +- docs/{ => tests}/glossary.rst | 0 docs/tests/index.rst | 23 +++ docs/tests/section1/index.rst | 9 + docs/tests/section1/subpage1.rst | 5 + docs/tests/section1/subpage2.rst | 5 + docs/tests/section2/index.rst | 12 ++ docs/tests/section2/section21/index.rst | 9 + docs/tests/section2/section21/subpage1.rst | 5 + docs/tests/section2/section21/subpage2.rst | 5 + docs/tests/section2/subpage1.rst | 5 + docs/tests/section2/subpage2.rst | 5 + src/crate/theme/rtd/__init__.py | 45 +++-- src/crate/theme/rtd/conf/__init__.py | 4 +- src/crate/theme/rtd/crate/sidebar.html | 2 +- src/crate/theme/rtd/crate/sidebartoc.html | 173 +----------------- .../rtd/crate/static/css/crateio-rtd.css | 9 - .../static/css/furo-collapsible-toc.scss | 36 ++++ .../theme/rtd/crate/static/css/index.css | 1 + src/crate/theme/rtd/crate/static/js/custom.js | 60 ++++++ src/crate/theme/rtd/sidebartoc.py | 140 ++++++++++++++ 23 files changed, 367 insertions(+), 200 deletions(-) rename docs/{ => tests}/glossary.rst (100%) create mode 100644 docs/tests/index.rst create mode 100644 docs/tests/section1/index.rst create mode 100644 docs/tests/section1/subpage1.rst create mode 100644 docs/tests/section1/subpage2.rst create mode 100644 docs/tests/section2/index.rst create mode 100644 docs/tests/section2/section21/index.rst create mode 100644 docs/tests/section2/section21/subpage1.rst create mode 100644 docs/tests/section2/section21/subpage2.rst create mode 100644 docs/tests/section2/subpage1.rst create mode 100644 docs/tests/section2/subpage2.rst create mode 100644 src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss create mode 100644 src/crate/theme/rtd/sidebartoc.py diff --git a/.gitignore b/.gitignore index 29ed94a72..e5b182c7a 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,4 @@ dist eggs node_modules* yarn-error.log +_* diff --git a/CHANGES.rst b/CHANGES.rst index 47186cab1..3faa5a003 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -5,6 +5,7 @@ CHANGES Unreleased ---------- +- Added TOC expand/collapse icons and more advanced navigation 2025/12/19 0.45.0 ----------------- diff --git a/docs/index.rst b/docs/index.rst index afe0874e2..5bf675529 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -57,17 +57,17 @@ The legacy feature gallery exclusively uses reStructuredText. .. toctree:: :maxdepth: 1 + headings admonitions codesnippets - diagrams - glossary - headings - images lists - projects - subpage tables + images + diagrams typography + subpage + projects + tests/index diff --git a/docs/glossary.rst b/docs/tests/glossary.rst similarity index 100% rename from docs/glossary.rst rename to docs/tests/glossary.rst diff --git a/docs/tests/index.rst b/docs/tests/index.rst new file mode 100644 index 000000000..099165ab8 --- /dev/null +++ b/docs/tests/index.rst @@ -0,0 +1,23 @@ +.. _tests: + +######################### +Navigation bar test pages +######################### + +1. Clicking the title should expand the section and navigate to the section page +2. Clicking just the icon should expand but not navigate to the section +3. Clicking just the icon for an expanded section should collapse that section and leave other expanded sections expanded +4. Hovering the mouse over an icon should show a fade background behind the icon +5. Hovering the mouse over the title should show a fade background behind the title and the icon +6. The current page should be highlighted in the navigation bar as the user navigates through the pages below. + + +**Pages:** + +.. toctree:: + :titlesonly: + :glob: + + section1/index + section2/index + * diff --git a/docs/tests/section1/index.rst b/docs/tests/section1/index.rst new file mode 100644 index 000000000..573670182 --- /dev/null +++ b/docs/tests/section1/index.rst @@ -0,0 +1,9 @@ +######### +Section 1 +######### + +.. toctree:: + :maxdepth: 1 + + subpage1 + subpage2 diff --git a/docs/tests/section1/subpage1.rst b/docs/tests/section1/subpage1.rst new file mode 100644 index 000000000..5bf540986 --- /dev/null +++ b/docs/tests/section1/subpage1.rst @@ -0,0 +1,5 @@ +########## +Subpage 1 +########## + +Test subpage 1. diff --git a/docs/tests/section1/subpage2.rst b/docs/tests/section1/subpage2.rst new file mode 100644 index 000000000..bc3eef888 --- /dev/null +++ b/docs/tests/section1/subpage2.rst @@ -0,0 +1,5 @@ +########## +Subpage 2 +########## + +Test subpage 2. diff --git a/docs/tests/section2/index.rst b/docs/tests/section2/index.rst new file mode 100644 index 000000000..c3805ce3a --- /dev/null +++ b/docs/tests/section2/index.rst @@ -0,0 +1,12 @@ +############ +Section 2 +############ + +.. toctree:: + :maxdepth: 1 + + section21/index + subpage1 + subpage2 + +Hi diff --git a/docs/tests/section2/section21/index.rst b/docs/tests/section2/section21/index.rst new file mode 100644 index 000000000..694473a7a --- /dev/null +++ b/docs/tests/section2/section21/index.rst @@ -0,0 +1,9 @@ +############ +Section 2.1 +############ + +.. toctree:: + :maxdepth: 1 + + subpage1 + subpage2 diff --git a/docs/tests/section2/section21/subpage1.rst b/docs/tests/section2/section21/subpage1.rst new file mode 100644 index 000000000..5bf540986 --- /dev/null +++ b/docs/tests/section2/section21/subpage1.rst @@ -0,0 +1,5 @@ +########## +Subpage 1 +########## + +Test subpage 1. diff --git a/docs/tests/section2/section21/subpage2.rst b/docs/tests/section2/section21/subpage2.rst new file mode 100644 index 000000000..bc3eef888 --- /dev/null +++ b/docs/tests/section2/section21/subpage2.rst @@ -0,0 +1,5 @@ +########## +Subpage 2 +########## + +Test subpage 2. diff --git a/docs/tests/section2/subpage1.rst b/docs/tests/section2/subpage1.rst new file mode 100644 index 000000000..5bf540986 --- /dev/null +++ b/docs/tests/section2/subpage1.rst @@ -0,0 +1,5 @@ +########## +Subpage 1 +########## + +Test subpage 1. diff --git a/docs/tests/section2/subpage2.rst b/docs/tests/section2/subpage2.rst new file mode 100644 index 000000000..bc3eef888 --- /dev/null +++ b/docs/tests/section2/subpage2.rst @@ -0,0 +1,5 @@ +########## +Subpage 2 +########## + +Test subpage 2. diff --git a/src/crate/theme/rtd/__init__.py b/src/crate/theme/rtd/__init__.py index 981c72081..8c57e1066 100644 --- a/src/crate/theme/rtd/__init__.py +++ b/src/crate/theme/rtd/__init__.py @@ -22,6 +22,7 @@ """CrateDB Sphinx theme for Read the Docs""" import os +from .sidebartoc import generate_crate_navigation_html VERSION = (0, 45, 0) @@ -32,27 +33,47 @@ def get_version(): return __version__ - def current_dir(): return os.path.abspath(os.path.dirname(__file__)) - def get_html_theme_path(): """Return list of HTML theme paths.""" return [current_dir()] - def get_html_static_path(): """Return list of HTML static paths.""" - current_dir = current_dir() - return [ - os.path.join(current_dir, "crate", "static"), - ] - + return [os.path.join(current_dir(), "crate", "static")] def get_html_template_path(): """Return list of HTML template paths.""" - current_dir = current_dir() - return [ - os.path.join(current_dir, "crate"), - ] + return [os.path.join(current_dir(), "crate")] + + +def _add_crate_navigation(app, pagename, templatename, context, doctree): + """ + Sphinx event handler: Add enhanced navigation to template context. + + Generates multi-project navigation HTML and processes it through + Furo's navigation enhancer to add collapsible icons and checkboxes. + """ + + from furo.navigation import get_navigation_tree + + navigation_html = generate_crate_navigation_html(context) + + # Process through Furo's navigation enhancer + enhanced_navigation = get_navigation_tree(navigation_html) + + # Add to context for use in templates + context["crate_navigation_tree"] = enhanced_navigation + +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, + } diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py index 173996756..b0bece435 100644 --- a/src/crate/theme/rtd/conf/__init__.py +++ b/src/crate/theme/rtd/conf/__init__.py @@ -33,6 +33,7 @@ exclude_trees = ["pyenv", "tmp", "out", "parts", "clients", "eggs"] extensions = [ + "crate.theme.rtd", # CrateDB theme extension with Furo navigation integration "myst_nb", "sphinx_copybutton", "sphinx_design", @@ -82,7 +83,8 @@ } # https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html#fontawesome-icons html_css_files = [ - "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css" + "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css", + # Note: furo-collapsible-toc.scss is bundled via index.css import ] html_extra_path = ["_extra"] diff --git a/src/crate/theme/rtd/crate/sidebar.html b/src/crate/theme/rtd/crate/sidebar.html index ebe24fe3a..0baa3ca8f 100644 --- a/src/crate/theme/rtd/crate/sidebar.html +++ b/src/crate/theme/rtd/crate/sidebar.html @@ -8,7 +8,7 @@ {% endif %} {% endif %} -