diff --git a/.gitignore b/.gitignore index 29ed94a7..e5b182c7 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 3a5fe642..ff3c656a 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -5,6 +5,7 @@ CHANGES Unreleased ---------- +- Added TOC expand/collapse icons and more advanced navigation - Added Stepper directive - Removed bottom three links in primary navigation: Academy, Integration Tutorials, Sample Applications diff --git a/docs/index.rst b/docs/index.rst index afe0874e..5bf67552 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 00000000..099165ab --- /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 00000000..57367018 --- /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 00000000..5bf54098 --- /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 00000000..bc3eef88 --- /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 00000000..c3805ce3 --- /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 00000000..694473a7 --- /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 00000000..5bf54098 --- /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 00000000..bc3eef88 --- /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 00000000..5bf54098 --- /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 00000000..bc3eef88 --- /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 c46780af..1abe8704 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,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 17399675..b0bece43 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 ebe24fe3..0baa3ca8 100644 --- a/src/crate/theme/rtd/crate/sidebar.html +++ b/src/crate/theme/rtd/crate/sidebar.html @@ -8,7 +8,7 @@ {% endif %} {% endif %} -