Use Furo's navigation component through sphinx-design-elements' linktree

CHANGES.rst

@@ -5,6 +5,8 @@ CHANGES
 
 Unreleased
 ----------
+- Use Furo's navigation component through ``sphinx-design-elements``'
+  ``linktree``. Thanks, @pradyunsg.
 
 2025/11/05 0.42.0
 -----------------

docs/myst/linktree.md

@@ -0,0 +1,12 @@
+# Link Tree
+
+
+## About
+
+The link tree is a programmable toc tree.
+
+
+## Example
+
+```{linktree}
+```

docs/rst/linktree.rst

@@ -0,0 +1,17 @@
+#########
+Link Tree
+#########
+
+
+*****
+About
+*****
+
+The link tree is a programmable toc tree.
+
+
+*******
+Example
+*******
+
+.. linktree::

setup.py

@@ -67,7 +67,7 @@
         "sphinx>=7.1,<9",
         "sphinx-basic-ng==1.0.0b2",
         "sphinx-copybutton>=0.3.1,<1",
-        "sphinx-design-elements==0.4.0",
+        "sphinx-design-elements @ git+https://github.com/tech-writing/sphinx-design-elements@linktree",
         "sphinx-inline-tabs",
         "sphinx-sitemap<2.10.0",
         "sphinx-togglebutton<1",

src/crate/theme/ext/navigation.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8; -*-
+#
+# Licensed to Crate (https://crate.io) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  Crate licenses
+# this file to you under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.  You may
+# obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# However, if you have executed another commercial license agreement
+# with Crate these terms will supersede the license and you may use the
+# software solely pursuant to the terms of the relevant commercial agreement.
+
+import logging
+import typing as t
+
+from sphinx.application import Sphinx
+
+from crate.theme.ext.sidebar import make_primary_tree
+from crate.theme.rtd import __version__
+from sphinx.builders.html import StandaloneHTMLBuilder
+
+logger = logging.getLogger(__name__)
+
+
+def html_page_context(
+        app: Sphinx,
+        pagename: str,
+        templatename: str,
+        context: t.Dict[str, t.Any],
+        doctree: t.Any,
+) -> None:
+    """
+    Sphinx HTML page context provider.
+    """
+    if not isinstance(app.builder, StandaloneHTMLBuilder):
+        raise Exception(
+            "Theme is being used with a non-HTML builder. "
+            "If you're seeing this error, it is a symptom of a mistake in your "
+            "configuration."
+        )
+
+    # Basic constants
+    context["theme_version"] = __version__
+
+    # Navigation tree component from `sphinx-design-elements`.
+    try:
+        primary_tree = make_primary_tree(builder=app.builder, context=context)
+        context["ng_navigation_tree"] = primary_tree.render()
+    except Exception as ex:
+        logger.exception("Unable to compute primary navigation tree")

src/crate/theme/ext/sidebar.py

@@ -0,0 +1,118 @@
+# -*- coding: utf-8; -*-
+#
+# Licensed to Crate (https://crate.io) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  Crate licenses
+# this file to you under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.  You may
+# obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# However, if you have executed another commercial license agreement
+# with Crate these terms will supersede the license and you may use the
+# software solely pursuant to the terms of the relevant commercial agreement.
+
+import typing as t
+
+from sphinx.builders.html import StandaloneHTMLBuilder
+
+from sphinx_design_elements.lib.linktree import LinkTree
+
+
+def make_primary_tree(builder: StandaloneHTMLBuilder, context: t.Dict[str, t.Any]) -> LinkTree:
+    """
+    A navigation tree demo defined with Python code.
+
+    It includes two sections:
+
+    - The vanilla toctree of the project at hand..
+    - A linktree composed of Sphinx references or URLs.
+    """
+    project_name = context["project"]
+
+    # Create LinkTree component.
+    linktree = LinkTree.from_context(builder=builder, context=context)
+    linktree.remove_from_title("CrateDB")
+    doc = linktree.api.doc
+    ref = linktree.api.ref
+    link = linktree.api.link
+
+    # Add section about project (self).
+    project = \
+        linktree \
+            .project(docname=project_name, title=project_name)
+
+    # .title("Customized TocTree") \
+
+    # 1. On specific projects, add the vanilla toctree.
+    #    Here, also customize it for demonstration purposes.
+    if project_name == "CrateDB documentation theme":
+
+        # Add vanilla project toctree.
+        project.toctree()
+
+        # Add custom navigation items.
+        # TODO: Find a way to pull additional navigation hints from project
+        #       markup itself, in order to get rid of this anomaly.
+        project.add(
+            doc(name="admonitions", label="Admonitions"),
+            doc(name="codesnippets", label="Code snippets"),
+            doc(name="myst/mermaid", label="Mermaid diagrams, written in Markdown"),
+        )
+
+    # 2. Add section with links to intersphinx targets.
+
+    # CrateDB Database.
+    linktree \
+        .title("CrateDB Database") \
+        .add(
+            ref(target="guide:getting-started", label="Getting started"),
+            ref(target="guide:index", label="CrateDB Handbook"),
+            ref(target="crate-reference:index", label="CrateDB Reference"),
+            ref(target="ctk:index", label="CrateDB Toolkit"),
+        )
+
+    # CrateDB Cloud.
+    linktree \
+        .title("CrateDB Cloud") \
+        .add(
+            ref("cloud:index"),
+            ref("cloud-cli:index"),
+        )
+
+    # CrateDB clients.
+    linktree \
+        .title("Clients") \
+        .add(
+            ref("crate-admin-ui:index"),
+            ref("crate-crash:index"),
+            ref("guide:connect"),
+            ref("connect-java"),
+            ref("crate-npgsql:index"),
+            ref("crate-dbal:index"),
+            ref("crate-pdo:index"),
+            ref("crate-python:index"),
+        )
+
+    # Other links.
+    linktree \
+        .title("Miscellaneous") \
+        .add(
+            link(uri="https://crate.io/support/", label="Support"),
+            link(uri="https://community.crate.io/", label="Community"),
+            link(uri="https://community.crate.io/t/overview-of-cratedb-integration-tutorials/1015", label="Integration tutorials"),
+            link(uri="https://github.com/crate/cratedb-examples", label="Integration examples"),
+            link(uri="https://github.com/crate/crate-sample-apps", label="Sample applications"),
+            ref("sql-99:index"),
+            # ref("crate-docs-theme:index"),
+            # ref("crate-docs:index"),
+    )
+
+    return linktree

src/crate/theme/rtd/conf/__init__.py

@@ -21,8 +21,8 @@
 import os
 
 from crate.theme import rtd as theme
+from crate.theme.ext import navigation
 from crate.theme.rtd import __version__
-from crate.theme.rtd.conf.furo import _html_page_context
 from os import environ
 
 source_suffix = ".rst"
@@ -103,6 +103,7 @@
     # CrateDB General
     'guide': ('https://cratedb.com/docs/guide/', None),
     'crate-reference': ('https://cratedb.com/docs/crate/reference/en/latest/', None),
+    'ctk': ('https://cratedb-toolkit.readthedocs.io/', None),
 
     # CrateDB Clients and Integrations
     'crate-admin-ui': ('https://cratedb.com/docs/crate/admin-ui/en/latest/', None),
@@ -171,6 +172,8 @@
     "https://unsplash.com/.*",
     # [Errno 101] Network is unreachable
     "https://www.gnu.org/.*",
+    # Temporary failure in name resolution
+    "https://jupysql.ploomber.io/.*",
 ]
 linkcheck_anchors_ignore_for_url = [
     # Requires JavaScript.
@@ -330,7 +333,7 @@ def apply_html_context_custom(app_inited):
 
     # Modern / NG / Furo.
     app.require_sphinx("3.0")
-    app.connect("html-page-context", _html_page_context)
+    app.connect("html-page-context", navigation.html_page_context)
 
     # Customizations.
     app.connect("builder-inited", configure_self_hosted_on_path)
@@ -347,4 +350,3 @@ def apply_html_context_custom(app_inited):
         "parallel_write_safe": True,
         "version": __version__,
     }
-

src/crate/theme/rtd/crate/components/github_feedback_compact.html

@@ -53,7 +53,7 @@
       <p class="sd-card-text">
         <span class="fa fa-code fa-fw"></span>
         &nbsp;
-        <a id="docs-feedback-open-github" class="feedback-compact-link" href="https://{{ github_host|default('github.com') }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default('blob') }}/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}?plain=1" rel="noopener" target="_blank" title="View page source on GitHub">View&nbsp;page source</a>
+        <a id="docs-feedback-open-github" class="feedback-compact-link" href="https://{{ github_host|default('github.com') }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default('blob') }}/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}?plain=true" rel="noopener" target="_blank" title="View page source on GitHub">View&nbsp;page source</a>
       </p>
       {% endif %}
 

src/crate/theme/rtd/crate/components/googlesearch.html

@@ -0,0 +1,9 @@
+<div role="complementary" class="bs-docs-sidebar hidden-print">
+  <div class="search-link">
+    {% if pagename == "search" %}
+    <a href="search.html" class="btn btn-primary">Search</a>
+    {% else %}
+    <a href="{{ pathto('search') }}" class="btn btn-primary">Search</a>
+    {% endif %}
+  </div>
+</div>

src/crate/theme/rtd/crate/sections/sidebar-primary.html

@@ -2,13 +2,21 @@
   <div class="sidebar-container">
     <div class="sidebar-sticky">
 
-      <!-- Section 1 
+      <!-- Section 1 + 2 -->
       <div class="sidebar-tree">
-        {# {- ng_navigation_tree } #}
-      </div> -->
+        {{ ng_navigation_tree }}
+      </div>
 
-      <!-- Section 2 -->
+      {% if project == 'CrateDB documentation theme' %}
+
+      <!-- Section 3 -->
+      <span class="sd-text-center sd-fs-5 sd-font-weight-bold sd-text-uppercase sd-text-secondary">
+        Legacy navigation
+      </span>
       {% include "sidebar.html" %}
+
+      {% endif %}
+
     </div>
   </div>
 </div>

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

@@ -169,7 +169,7 @@ div.hero.danger {
 }
 .bs-docs-sidebar {
   padding: 0px 20px 8px 16px;
-  margin-bottom: 20px;
+  /* margin-bottom: 20px; */
 }
 
 .affix {

src/crate/theme/rtd/crate/static/css/ng/furo.scss

@@ -101,3 +101,8 @@ article p:has(+ ul),
 article p:has(+ ol) {
   margin-bottom: 4px;
 }
+
+// Sidebar NG: Adjust margins.
+.sidebar-tree {
+  margin-top: unset;
+}