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

Author: amotl

CHANGES.rst

@@ -16,6 +16,8 @@ Unreleased
 - Add new ``cloud-docs`` documentation project
 - Switch to modern responsive 3-column layout theme ``sphinx-basic-ng``.
   Thanks, @pradyunsg.
+- Use Furo's navigation component through ``sphinx-design-elements``'
+  ``linktree``. Thanks, @pradyunsg.
 
 
 2023/05/15 0.27.1

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-basic-ng==1.0.0b2",
         "sphinx-copybutton>=0.3.1,<1",
         "sphinx-design<1",
-        "sphinx-design-elements==0.1.0",
+        "sphinx-design-elements==0.2.0",
         "sphinx-inline-tabs",
         "sphinx-sitemap>=2,<3",
         "sphinx-subfigure<1",

src/crate/theme/ext/__init__.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/navigation.py

@@ -0,0 +1,108 @@
+# -*- 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:
+    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") \
+
+    # On specific projects, customize the link tree.
+    # TODO: Find a way to pull additional navigation hints from project
+    #       markup itself, in order to get rid of this anomaly.
+    if project_name == "CrateDB Docs Theme":
+        project.add(
+            doc(name="admonitions", label="Admonitions"),
+            doc(name="codesnippets", label="Code snippets"),
+            doc(name="myst/mermaid", label="Mermaid diagrams, written in Markdown"),
+        )
+
+    # Add project toctree.
+    project.toctree()
+
+    # Add section with links to intersphinx targets.
+
+    # CrateDB Database.
+    linktree \
+        .title("CrateDB Database") \
+        .add(
+            ref(target="crate-reference:index", label="CrateDB Reference"),
+            ref(target="crate-tutorials:index", label="Install CrateDB"),
+            ref(target="crate-howtos:index", label="Getting started"),
+        )
+
+    # CrateDB Cloud.
+    linktree \
+        .title("CrateDB Cloud") \
+        .add(
+            ref("cloud-reference:index"),
+            ref("cloud-tutorials:index"),
+            ref("cloud-howtos:index"),
+            ref("cloud-cli:index"),
+        )
+
+    # CrateDB clients.
+    linktree \
+        .title("Clients") \
+        .add(
+            ref("crate-admin-ui:index"),
+            ref("crate-crash:index"),
+            ref("crate-clients-tools:index"),
+            ref("crate-jdbc:index"),
+            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="Stacks and 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/ext/sidebar.py

@@ -20,8 +20,8 @@
 # software solely pursuant to the terms of the relevant commercial agreement.
 
 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"
@@ -250,9 +250,9 @@ def apply_html_context_custom(app_inited):
         except Exception as ex:
             print(f"ERROR: Unable to adjust `html_context`. Reason: {ex}")
 
-    # Modern / NG / Furo.
+    # NG: Initialize navigation tree component from `sphinx-design-elements`.
     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", force_canonical_url)
@@ -265,4 +265,3 @@ def apply_html_context_custom(app_inited):
         "parallel_write_safe": True,
         "version": __version__,
     }
-

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

@@ -25,7 +25,7 @@
 # You can change the `project` value to anything you want because
 # `src/crate/theme/rtd/crate/sidebartoc.html` does not have a menu item for
 # this project.
-project = u"CrateDB Fake Docs"
+project = "CrateDB Docs Theme"
 html_title = project
 
 url_path = "docs/fake"

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

@@ -51,7 +51,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>
     </div>
   </details>

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

@@ -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/components/github_feedback_compact.html

@@ -2,13 +2,26 @@
   <div class="sidebar-container">
     <div class="sidebar-sticky">
 
-      <!-- Section 1 -->
+      <!-- Google search -->
+      {% include "components/googlesearch.html" %}
+
+      <!-- NG Production -->
       <div class="sidebar-tree">
         {{ ng_navigation_tree }}
       </div>
 
-      <!-- Section 2 -->
+      {#
+      {% if project == 'CrateDB Docs Theme' %}
+
+      <!-- Static HTML -->
+      <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/components/googlesearch.html

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

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

@@ -36,3 +36,8 @@
     position: unset;
   }
 }
+
+// Sidebar NG: Adjust margins.
+.sidebar-tree {
+  margin-top: unset;
+}