Support full TOC from a project and use for Guides project.

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
 -----------------

DEVELOP.rst

@@ -100,13 +100,27 @@ dynamically generated using the ``toctree`` directive, but you can also add
 static links to the sidebar TOC by editing the HTML file directly. This is where
 you add entries to the top level sections in the sidebar TOC.
 
-
 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.
-requirements.txt file to include the full path to the 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

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/

src/crate/theme/rtd/__init__.py

@@ -25,7 +25,7 @@
 
 VERSION = (0, 40, 1)
 
-__version__ = ".".join(str(v) for v in VERSION)
+__version__ = ".".join(str(v) for v in VERSION) # + ".dev0"
 __version_full__ = __version__
 
 

src/crate/theme/rtd/crate/sidebartoc.html

@@ -16,14 +16,27 @@
     </div>
   </li>
 
-  <!-- Home. -->
-  {% if project == 'CrateDB: Guide' and pagename == 'home/index' %}
-    <li class="navleft-item current"><a class="current-active" href="/docs/guide/home/">Overview</a></li>
+  <!-- Section A: -->
+  {% if project == 'CrateDB: Guide' %}
+    <!-- Show root index page in the Guide project selected if needed -->
+    {% if pagename == 'index' %}
+      <li class="current">
+        <a class="current-active" href="{{ pathto(master_doc) }}">Overview</a>
+      </li>
+    {% else %}
+      <li class="navleft-item"><a href="{{ pathto(master_doc) }}">Overview</a></li>
+    {% endif %}
+    <!-- Show all remaining TOC entries in the root -->
+    <li class="current toctree-l0">
+      {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }}
+    </li>
   {% else %}
-    <li class="navleft-item"><a href="/docs/guide/home/">Overview</a></li>
+    <!-- Show Guide sections as links in other projects -->
+    <li class="navleft-item"><a href="/docs/guide/">Overview</a></li>
+    <li class="navleft-item"><a href="/docs/guide/start/">Getting Started</a></li>
+    <li class="navleft-item"><a href="/docs/guide/handbook/">Handbook</a></li>
   {% endif %}
 
-  <!-- Section A. -->
   {% if project == 'CrateDB Cloud' %}
     <li class="current">
       <a class="current-active" href="{{ pathto(master_doc) }}">CrateDB Cloud</a>
@@ -33,15 +46,6 @@
     <li class="navleft-item"><a href="/docs/cloud/">CrateDB Cloud</a></li>
   {% endif %}
 
-  {% if project == 'CrateDB: Guide' and pagename != 'home/index' %}
-    <li class="current">
-      <a class="current-active" href="{{ pathto(master_doc) }}">Guides</a>
-      {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }}
-    </li>
-  {% else %}
-    <li class="navleft-item"><a href="/docs/guide/">Guides</a></li>
-  {% endif %}
-
   {% if project == 'CrateDB: Reference' %}
     <li class="current">
       <a class="current-active" href="{{ pathto(master_doc) }}">Reference Manual</a>
@@ -51,7 +55,6 @@
     <li class="navleft-item"><a href="/docs/crate/reference/">Reference Manual</a></li>
   {% endif %}
 
-
   <!-- Section B. -->
   {% if project == 'CrateDB: Admin UI' %}
   <li class="current border-top">

src/crate/theme/rtd/crate/static/css/crateio-rtd.css

@@ -157,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;
 }