From 9b70eb8c766857d5a03b2d2577d4c0411aaed110 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Tue, 16 Dec 2025 21:54:18 +0100 Subject: [PATCH 01/10] Update docs test --- 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 +++++ 12 files changed, 89 insertions(+), 6 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 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..0ed348f0d --- /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..c854c0b11 --- /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. From 90bf9ea5b3b6d16a19836b12eddf58a38453b402 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Tue, 16 Dec 2025 21:54:48 +0100 Subject: [PATCH 02/10] Ignore temp folders starting with _ --- .gitignore | 1 + 1 file changed, 1 insertion(+) 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 +_* From 8b5b761e50d6bdaf3ce500cc24c9bfa0c6a25a74 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Tue, 16 Dec 2025 22:00:58 +0100 Subject: [PATCH 03/10] Introduce Furo TOC navigation with icons and individual section states --- src/crate/theme/rtd/__init__.py | 35 +++- 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 | 48 +++++ src/crate/theme/rtd/sidebartoc.py | 141 ++++++++++++++ 9 files changed, 263 insertions(+), 186 deletions(-) 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/src/crate/theme/rtd/__init__.py b/src/crate/theme/rtd/__init__.py index c46780afd..1f49ee86e 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, 42, 0) @@ -32,16 +33,13 @@ 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() @@ -49,10 +47,39 @@ def get_html_static_path(): 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"), ] + + +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 %} -