NG: Switch to modern responsive 3-column layout theme sphinx-basic-ng

CHANGES.rst

@@ -5,6 +5,8 @@ CHANGES
 
 Unreleased
 ----------
+- Switch to modern responsive 3-column layout theme ``sphinx-basic-ng``.
+  Thanks, @pradyunsg.
 
 2024/07/25 0.33.2
 -----------------

docs/build.json

@@ -1,5 +1,5 @@
 {
   "schemaVersion": 1,
   "label": "docs build",
-  "message": "2.1.1"
+  "message": "2.1.2"
 }

docs/index.rst

@@ -56,17 +56,17 @@ The legacy feature gallery exclusively uses reStructuredText.
 .. toctree::
     :maxdepth: 1
 
-    headings
     admonitions
-    lists
-    tables
-    images
-    diagrams
     codesnippets
-    typography
-    subpage
+    diagrams
     glossary
+    headings
+    images
+    lists
     projects
+    subpage
+    tables
+    typography
 
 
 

package.json

@@ -6,6 +6,9 @@
     "jquery": "^3.7.1",
     "js-cookie": "^3.0.5",
     "normalize.css": "^8.0.1",
+    "postcss-loader": "^7.3",
+    "sass": "^1.60.0",
+    "sass-loader": "^13.2",
     "sticky-sidebar": "^3.3.1",
     "style-loader": "^4.0",
     "webpack": "^5.92",

setup.py

@@ -53,14 +53,18 @@
     keywords="crate docs sphinx readthedocs",
     license="Apache License 2.0",
     packages=find_namespace_packages(where="src"),
+    namespace_packages=["crate"],
     package_dir={"": "src"},
     include_package_data=True,
     zip_safe=False,
     install_requires=[
-        "Jinja2>=3,<3.2",
-        "docutils==0.16",
+        "docutils",
+        "docutils-stubs==0.0.22",
+        "furo==2024.05.06",
+        "jinja2>=3,<4",
         "myst-parser[linkify]<4",
         "sphinx>=4.6,<7",
+        "sphinx-basic-ng==1.0.0b2",
         "sphinx-copybutton>=0.3.1,<1",
         "sphinx-design-elements==0.4.0",
         "sphinx-inline-tabs",

src/crate/__init__.py

@@ -0,0 +1,3 @@
+from pkg_resources import declare_namespace
+
+declare_namespace("crate")

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

@@ -20,6 +20,8 @@
 # software solely pursuant to the terms of the relevant commercial agreement.
 
 from crate.theme import rtd as theme
+from crate.theme.rtd import __version__
+from crate.theme.rtd.conf.furo import _html_page_context
 from os import environ
 
 source_suffix = ".rst"
@@ -161,9 +163,12 @@
 
 # Configure linkchecker
 linkcheck_ignore = [
+    # Well.
+    "https://example.org/.*",
     # Breaks accessibility via JS ¯\_(ツ)_/¯
     "https://www.iso.org/obp/ui/.*",
-    "https://example.org/.*",
+    # 403 Client Error: Forbidden for url
+    "https://unsplash.com/.*",
 ]
 linkcheck_retries = 3
 linkcheck_timeout = 15
@@ -281,7 +286,19 @@ def apply_html_context_custom(app_inited):
         except Exception as ex:
             print(f"ERROR: Unable to adjust `html_context`. Reason: {ex}")
 
+    # Modern / NG / Furo.
+    app.require_sphinx("3.0")
+    app.connect("html-page-context", _html_page_context)
+
+    # Customizations.
     app.connect("builder-inited", configure_self_hosted_on_path)
     app.connect("builder-inited", set_proxied_api_host)
     app.connect("builder-inited", set_proxied_static_path)
     app.connect("builder-inited", apply_html_context_custom)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+        "version": __version__,
+    }
+

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

@@ -0,0 +1,54 @@
+"""
+Vendored version of Furo's navigation tree component.
+
+https://github.com/pradyunsg/furo/blob/main/src/furo/navigation.py
+"""
+import sphinx
+import typing as t
+
+from furo import get_navigation_tree
+
+from crate.theme.rtd import __version__
+from sphinx.builders.html import StandaloneHTMLBuilder
+
+
+def furo_compute_navigation_tree(context: t.Dict[str, t.Any]) -> str:
+    """
+    The navigation tree, generated from the sphinx-provided ToC tree.
+    """
+    if "toctree" in context:
+        toctree = context["toctree"]
+        toctree_html = toctree(
+            collapse=False,
+            titles_only=True,
+            maxdepth=-1,
+            includehidden=True,
+        )
+    else:
+        toctree_html = ""
+
+    return get_navigation_tree(toctree_html)
+
+
+def _html_page_context(
+    app: sphinx.application.Sphinx,
+    pagename: str,
+    templatename: str,
+    context: t.Dict[str, t.Any],
+    doctree: t.Any,
+) -> None:
+    """
+    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__
+
+    # Values computed from page-level context.
+    context["ng_navigation_tree"] = furo_compute_navigation_tree(context)

src/crate/theme/rtd/crate/base.html

@@ -235,17 +235,5 @@ <h3>{{ _('Navigation') }}</h3>
     </div>
 {%- endblock %}
 
-    {%- if project != 'SQL 99' %}
-    <!-- Algolia DocSearch  -->
-    <script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>
-    <script type="text/javascript"> 
-      docsearch({
-        container: '#docsearch',
-        appId: 'AZ1NEV7CG0',
-        apiKey: '84b128d95218b1eddb2d4b82d25291fe',
-        indexName: 'cratedb',
-      });
-    </script>
-    {%- endif %}
   </body>
 </html>

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

@@ -1,8 +1,10 @@
 <!-- GitHub feedback component: Links to report issue, and source/edit links -->
 
-{%
-set source_path = conf_py_path + pagename + suffix
-%}
+
+{% import "settings.html" as settings with context %}
+
+{% set suffix = settings.suffix %}
+{% set source_path = conf_py_path + pagename + suffix %}
 
 <div class="feedback-compact-container">
   <details class="sd-sphinx-override sd-dropdown sd-card sd-mb-0 sd-fade-in feedback-compact-content">  <!-- open="" -->

src/crate/theme/rtd/crate/github_keynav.js → src/crate/theme/rtd/crate/components/github_keynav.js

@@ -2,6 +2,11 @@
  * Keyboard navigation for GitHub. CTRL+G will navigate to
  * the edit page on GitHub for the corresponding document.
 **/
+
+{% import "settings.html" as settings with context %}
+
+{% set suffix = settings.suffix %}
+
 document.addEventListener('keydown', (event) => {
   if (event.key === 'g' && event.ctrlKey) {
     {% if check_meta and 'github_url' in meta %}

src/crate/theme/rtd/crate/components/related-pages.html

@@ -0,0 +1,28 @@
+<div class="related-pages">
+  {% if next -%}
+    <a class="next-page" href="{{ next.link }}">
+      <div class="page-info">
+        <div class="context">
+          <span>{{ _("Next") }}</span>
+        </div>
+        <div class="title">{{ next.title }}</div>
+      </div>
+      <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+    </a>
+  {%- endif %}
+  {% if prev -%}
+    <a class="prev-page" href="{{ prev.link }}">
+      <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+      <div class="page-info">
+        <div class="context">
+          <span>{{ _("Previous") }}</span>
+        </div>
+        {% if prev.link == pathto(master_doc) %}
+        <div class="title">{{ _("Home") }}</div>
+        {% else %}
+        <div class="title">{{ prev.title }}</div>
+        {% endif %}
+      </div>
+    </a>
+  {%- endif %}
+</div>

src/crate/theme/rtd/crate/components/toggle-sidebar-primary.html

@@ -0,0 +1,5 @@
+<label for="sb-sidebar-toggle--primary" class="hide-when-primary-sidebar-shown" role="button">
+  {% block content %}
+  <i class="icon" title="Toggle site navigation sidebar"><svg><use href="#svg-menu"></use></svg></i>
+  {% endblock content %}
+</label>

src/crate/theme/rtd/crate/components/toggle-sidebar-secondary.html

@@ -0,0 +1,5 @@
+<label for="sb-sidebar-toggle--secondary" class="hide-when-secondary-sidebar-shown" role="button">
+  {% block content %}
+  <i class="icon" title="Toggle table of contents sidebar"><svg><use href="#svg-toc"></use></svg></i>
+  {% endblock content %}
+</label>

src/crate/theme/rtd/crate/layout.html → src/crate/theme/rtd/crate/layout_legacy.html

@@ -58,7 +58,7 @@
   {% block sidebarsourcelink %}{% endblock %}
 
   {%- block content %}
-  {% include "navbar.html" %}
+  {# include "navbar.html" #}
 
   <div class="w-canvas">
     {% if project == 'SQL 99' %}
@@ -126,11 +126,6 @@
       </div>
     </div>
   </div>
-  {% if project == 'SQL 99' %}
-  {%- include "footer_sql99.html" %}
-  {% else %}
-  {%- include "footer.html" %}
-  {% endif %}
 
   {%- endblock %}