From ca2ab3794ef105ba078b360e67d43eb11ce0b601 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Tue, 30 Sep 2025 10:00:28 +0200 Subject: [PATCH 01/10] Remove Guides heading from sidebar --- src/crate/theme/rtd/crate/sidebartoc.html | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/src/crate/theme/rtd/crate/sidebartoc.html b/src/crate/theme/rtd/crate/sidebartoc.html index dece555f..bb13af69 100644 --- a/src/crate/theme/rtd/crate/sidebartoc.html +++ b/src/crate/theme/rtd/crate/sidebartoc.html @@ -24,22 +24,19 @@ {% endif %} - {% if project == 'CrateDB Cloud' %} -
  • - CrateDB Cloud - {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }} -
    • + {% if project == 'CrateDB: Guide' and pagename != 'home/index' %} + {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }} {% else %} -
  • CrateDB Cloud
    • +
  • Guides
    • {% endif %} - {% if project == 'CrateDB: Guide' and pagename != 'home/index' %} + {% if project == 'CrateDB Cloud' %}
  • - Guides + CrateDB Cloud {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }}
    • {% else %} -
  • Guides
    • +
  • CrateDB Cloud
    • {% endif %} {% if project == 'CrateDB: Reference' %} @@ -51,7 +48,6 @@
  • Reference Manual
    • {% endif %} - {% if project == 'CrateDB: Admin UI' %}
  • From e72f24d178ff559644b88ff6c53fd02549f49071 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Sat, 4 Oct 2025 10:45:10 +0200 Subject: [PATCH 02/10] CSS for unindenting TOC entries --- src/crate/theme/rtd/crate/static/css/crateio-rtd.css | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/crate/theme/rtd/crate/static/css/crateio-rtd.css b/src/crate/theme/rtd/crate/static/css/crateio-rtd.css index 4e798270..b9487f0d 100644 --- a/src/crate/theme/rtd/crate/static/css/crateio-rtd.css +++ b/src/crate/theme/rtd/crate/static/css/crateio-rtd.css @@ -8,6 +8,18 @@ list-style: none; } +/* Remove indentation for toctree-l0 - used to unindent TOC level-1 to level-0 */ +.toctree-l0 { + margin-left: 0; + padding-left: 0; +} + +.toctree-l0 > ul { + margin-left: 0; + padding-left: 0; +} + + a.current, a.current-active { font-weight: 600; From 3f9fee1184051792c86c8187ecc39393d5178f97 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Sun, 5 Oct 2025 00:39:12 +0200 Subject: [PATCH 03/10] Fix CSS --- src/crate/theme/rtd/crate/sidebartoc.html | 19 +++++++++---------- .../rtd/crate/static/css/crateio-rtd.css | 19 +++++++------------ 2 files changed, 16 insertions(+), 22 deletions(-) diff --git a/src/crate/theme/rtd/crate/sidebartoc.html b/src/crate/theme/rtd/crate/sidebartoc.html index bb13af69..ddb3ec54 100644 --- a/src/crate/theme/rtd/crate/sidebartoc.html +++ b/src/crate/theme/rtd/crate/sidebartoc.html @@ -16,18 +16,17 @@
    • - - {% if project == 'CrateDB: Guide' and pagename == 'home/index' %} -
  • Overview
    • + + {% if project == 'CrateDB: Guide' %} + +
  • + {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }} +
    • {% else %} +
  • Overview
    • - {% endif %} - - - {% if project == 'CrateDB: Guide' and pagename != 'home/index' %} - {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }} - {% else %} -
  • Guides
    • +
  • Getting Started
    • +
  • Guides
    • {% endif %} {% if project == 'CrateDB Cloud' %} diff --git a/src/crate/theme/rtd/crate/static/css/crateio-rtd.css b/src/crate/theme/rtd/crate/static/css/crateio-rtd.css index b9487f0d..61132d73 100644 --- a/src/crate/theme/rtd/crate/static/css/crateio-rtd.css +++ b/src/crate/theme/rtd/crate/static/css/crateio-rtd.css @@ -8,18 +8,6 @@ list-style: none; } -/* Remove indentation for toctree-l0 - used to unindent TOC level-1 to level-0 */ -.toctree-l0 { - margin-left: 0; - padding-left: 0; -} - -.toctree-l0 > ul { - margin-left: 0; - padding-left: 0; -} - - a.current, a.current-active { font-weight: 600; @@ -169,6 +157,13 @@ div.hero.danger { .bs-docs-sidenav .toctree ul li.active > ul { display: block !important; } + +/* Remove indentation for toctree-l0 wrapper - used to display TOC entries at top level */ +.bs-docs-sidenav .toctree li.toctree-l0 > ul, +.bs-docs-sidenav .toctree li.toctree-l0 > ul > li { + padding-left: 0 !important; +} + .bs-docs-sidenav { padding-left: 0px; } From e8334570ffc4152a33685ea825f01177a7ce84a3 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Sun, 5 Oct 2025 20:13:38 +0200 Subject: [PATCH 04/10] add documentation about testing --- DEVELOP.rst | 28 +++++++++++++++++++++++++--- README.rst | 7 +++++-- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/DEVELOP.rst b/DEVELOP.rst index 4a67585f..fe2ac4c9 100644 --- a/DEVELOP.rst +++ b/DEVELOP.rst @@ -92,11 +92,33 @@ order to run the setup on, e.g., Linux, invoke those commands - YMMV:: sudo npm install --global yarn +TOC +--- +The theme also controls the TOC of the entire documentation in the left sidebar +of the rendered docs. The root entries of the TOC is defined in the +``sidebartoc.html`` file. + Testing changes =============== -If you want to see the effect of theme changes beyond the docs included in this project, -you can use the theme locally with any other docs project, by changing the projects -requirements.txt file to include the full path to local version of this project. +If you want to see the effect of theme changes beyond the docs included in this +project, you can use the theme locally with any other docs project by changing +the project's requirements.txt file to include the full path to the local +version of this project like this:: + + -e /full/path/to/crate-docs-theme + +Then, run ``make reset`` and ``make dev`` in the other project's ``docs`` +directory. + +.. note:: + + Since changes to CSS is packed into a bundle, you must run + ``make bundle-develop`` in the top-level directory of this project + whenever you make changes to CSS files. Or use ``make bundle-watch`` + to have the bundling process run continuously in the background. + + IF you are only changing .html files, you do not need to run the + bundling process. Release diff --git a/README.rst b/README.rst index c9a5c3f9..e8e22ea4 100644 --- a/README.rst +++ b/README.rst @@ -51,7 +51,10 @@ Configuration ------------- The documentation is composed of multiple separate documentation -projects, seamlessly interlinked via the CrateDB Documentation Theme. +projects, interlinked via the CrateDB Documentation Theme. + +To update the root of the TOC sidebar for the entire documentation, update the +`sidebartoc.html`` file. To use the theme, add this line to your Sphinx ``conf.py`` file:: @@ -77,7 +80,7 @@ Looking for more help? - Check out our `support channels`_ - +.. _sidebartoc.html: src/crate/theme/rtd/crate/templates/crate/sidebartoc.html .. _contribution docs: CONTRIBUTING.rst .. _Crate.io: https://cratedb.com .. _CrateDB documentation: https://cratedb.com/docs/ From d9f49ed26372ba900f4851be62bb76dadd8a7313 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Sun, 5 Oct 2025 20:51:29 +0200 Subject: [PATCH 05/10] Updated Changes.rst --- CHANGES.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGES.rst b/CHANGES.rst index adbc77b1..fcb35d65 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -5,6 +5,10 @@ CHANGES Unreleased ---------- +- Added support for including the entire level0 entries in the sidebar TOC for a +project. See the "CreateDB: Guide" project in the ``sidebartoc.html`` file for +how to do that. +- The Guide project is now utilizing this to show 3 top-level entries in the TOC. 2025/09/23 0.40.1 ----------------- From 50e7124c73f0f8ab8ff51740dbc7a5444f813108 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Mon, 6 Oct 2025 16:31:08 +0200 Subject: [PATCH 06/10] rename guide to handbook --- src/crate/theme/rtd/crate/sidebartoc.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/crate/theme/rtd/crate/sidebartoc.html b/src/crate/theme/rtd/crate/sidebartoc.html index ddb3ec54..4eda03f7 100644 --- a/src/crate/theme/rtd/crate/sidebartoc.html +++ b/src/crate/theme/rtd/crate/sidebartoc.html @@ -26,7 +26,7 @@
  • Overview
  • Getting Started
    • -
  • Guides
    • +
  • Handbook
    • {% endif %} {% if project == 'CrateDB Cloud' %} From d8aa4d3d41a0db32560b57488670dd9ab579c7ff Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Mon, 6 Oct 2025 16:31:41 +0200 Subject: [PATCH 07/10] temporary dev1 version --- src/crate/theme/rtd/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/crate/theme/rtd/__init__.py b/src/crate/theme/rtd/__init__.py index b045236c..dd5dc00e 100644 --- a/src/crate/theme/rtd/__init__.py +++ b/src/crate/theme/rtd/__init__.py @@ -23,9 +23,9 @@ import os -VERSION = (0, 40, 1) +VERSION = (0, 41, 0) -__version__ = ".".join(str(v) for v in VERSION) +__version__ = ".".join(str(v) for v in VERSION) + ".dev1" __version_full__ = __version__ From c29794aac449cef6b4ab2de14f80fe6814e9e55a Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Mon, 6 Oct 2025 22:12:53 +0200 Subject: [PATCH 08/10] Revert the version change - will be done separately. --- src/crate/theme/rtd/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/crate/theme/rtd/__init__.py b/src/crate/theme/rtd/__init__.py index dd5dc00e..6f2359a4 100644 --- a/src/crate/theme/rtd/__init__.py +++ b/src/crate/theme/rtd/__init__.py @@ -23,9 +23,9 @@ import os -VERSION = (0, 41, 0) +VERSION = (0, 40, 1) -__version__ = ".".join(str(v) for v in VERSION) + ".dev1" +__version__ = ".".join(str(v) for v in VERSION) # + ".dev0" __version_full__ = __version__ From 5f48c16fea5d26172dbdb159a5ca1bca4c19ca02 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Wed, 8 Oct 2025 15:19:31 +0200 Subject: [PATCH 09/10] Special handling of root page --- src/crate/theme/rtd/crate/sidebartoc.html | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/src/crate/theme/rtd/crate/sidebartoc.html b/src/crate/theme/rtd/crate/sidebartoc.html index 4eda03f7..da38aec5 100644 --- a/src/crate/theme/rtd/crate/sidebartoc.html +++ b/src/crate/theme/rtd/crate/sidebartoc.html @@ -18,13 +18,21 @@ {% if project == 'CrateDB: Guide' %} - + + {% if pagename == 'index' %} +
  • + Overview +
    • + {% else %} +
  • Overview
    • + {% endif %} +
  • {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }}
    • {% else %} -
  • Overview
    • +
  • Overview
  • Getting Started
  • Handbook
    • {% endif %} From 65622a94cd3305a95925f436a27120725c214bff Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Wed, 8 Oct 2025 15:23:53 +0200 Subject: [PATCH 10/10] fix comment --- src/crate/theme/rtd/crate/sidebartoc.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/crate/theme/rtd/crate/sidebartoc.html b/src/crate/theme/rtd/crate/sidebartoc.html index da38aec5..2f81b192 100644 --- a/src/crate/theme/rtd/crate/sidebartoc.html +++ b/src/crate/theme/rtd/crate/sidebartoc.html @@ -18,7 +18,7 @@ {% if project == 'CrateDB: Guide' %} - + {% if pagename == 'index' %}
  • Overview