diff --git a/CHANGES.rst b/CHANGES.rst
index 703ff9396..12b4b8b33 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -202,6 +202,8 @@ Unreleased
- Remove external links indicator
- Improve visual appearance of admonition components
- Add new ``cloud-docs`` documentation project
+- Switch to modern responsive 3-column layout theme ``sphinx-basic-ng``.
+ Thanks, @pradyunsg.
2023/05/15 0.27.1
diff --git a/docs/build.json b/docs/build.json
index 5647caf4a..5de7837be 100644
--- a/docs/build.json
+++ b/docs/build.json
@@ -1,5 +1,5 @@
{
"schemaVersion": 1,
"label": "docs build",
- "message": "2.1.1"
+ "message": "2.1.2"
}
diff --git a/docs/codesnippets.rst b/docs/codesnippets.rst
old mode 100644
new mode 100755
diff --git a/docs/diagrams.rst b/docs/diagrams.rst
old mode 100644
new mode 100755
diff --git a/docs/headings.rst b/docs/headings.rst
old mode 100644
new mode 100755
diff --git a/docs/images.rst b/docs/images.rst
old mode 100644
new mode 100755
diff --git a/docs/index.rst b/docs/index.rst
old mode 100644
new mode 100755
index 0df817873..0b70af8c6
--- a/docs/index.rst
+++ b/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
diff --git a/docs/lists.rst b/docs/lists.rst
old mode 100644
new mode 100755
diff --git a/docs/subpage.rst b/docs/subpage.rst
old mode 100644
new mode 100755
diff --git a/docs/tables.rst b/docs/tables.rst
old mode 100644
new mode 100755
diff --git a/package.json b/package.json
index b6796140f..dd048cc78 100644
--- a/package.json
+++ b/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",
diff --git a/setup.py b/setup.py
index 77d177e22..2bbe4f4b0 100644
--- a/setup.py
+++ b/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",
diff --git a/src/crate/__init__.py b/src/crate/__init__.py
index e69de29bb..d5fe4404f 100644
--- a/src/crate/__init__.py
+++ b/src/crate/__init__.py
@@ -0,0 +1,3 @@
+from pkg_resources import declare_namespace
+
+declare_namespace("crate")
diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py
index bf2c3c5ec..897b1bf21 100644
--- a/src/crate/theme/rtd/conf/__init__.py
+++ b/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__,
+ }
+
diff --git a/src/crate/theme/rtd/conf/furo.py b/src/crate/theme/rtd/conf/furo.py
new file mode 100644
index 000000000..bae727b84
--- /dev/null
+++ b/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)
diff --git a/src/crate/theme/rtd/crate/base.html b/src/crate/theme/rtd/crate/base.html
index 3e1429d7c..f50211791 100644
--- a/src/crate/theme/rtd/crate/base.html
+++ b/src/crate/theme/rtd/crate/base.html
@@ -235,17 +235,5 @@ {{ _('Navigation') }}
{%- endblock %}
- {%- if project != 'SQL 99' %}
-
-
-
- {%- endif %}