From ea7adf97988d2e2a5b46963ad4a923b645afdad1 Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Sun, 27 Sep 2026 18:31:07 +0200 Subject: [PATCH 01/10] feat: RTD version selector --- .pre-commit-config.yaml | 8 ++- biome.jsonc | 5 ++ pyproject.toml | 4 ++ src/scverse_doc/theme/__init__.py | 1 + .../scverse/components/scverse-ecosystem.html | 54 +++++++++---------- .../scverse/components/scverse-footer.html | 10 ++-- src/scverse_doc/theme/scverse/layout.html | 5 ++ .../theme/scverse/static/js/readthedocs.js | 30 +++++++++++ src/scverse_doc/theme/scverse/theme.conf | 26 --------- src/scverse_doc/theme/scverse/theme.toml | 27 ++++++++++ 10 files changed, 109 insertions(+), 61 deletions(-) create mode 100644 src/scverse_doc/theme/scverse/layout.html create mode 100644 src/scverse_doc/theme/scverse/static/js/readthedocs.js delete mode 100644 src/scverse_doc/theme/scverse/theme.conf create mode 100644 src/scverse_doc/theme/scverse/theme.toml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 34b4ce4..be85adf 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -17,8 +17,13 @@ repos: hooks: - id: pyproject-fmt groups: [format] + - repo: https://github.com/djlint/djLint + rev: v1.46.2 + hooks: + - id: djlint-reformat + - id: djlint - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.16.8 + rev: v0.16.9 hooks: - id: ruff-check args: [--fix, --exit-non-zero-on-fix] @@ -51,7 +56,6 @@ repos: # Check that there are no merge conflicts (could be generated by template sync) - id: check-merge-conflict args: [--assume-in-merge] - - repo: https://github.com/zizmorcore/zizmor-pre-commit rev: v1.30.1 hooks: diff --git a/biome.jsonc b/biome.jsonc index 74b4277..d7a7e97 100644 --- a/biome.jsonc +++ b/biome.jsonc @@ -10,6 +10,11 @@ ], }, "formatter": { "useEditorconfig": true }, + "javascript": { + "formatter": { + "semicolons": "asNeeded", + }, + }, "overrides": [ { "includes": ["./.vscode/*.json", "**/*.jsonc"], diff --git a/pyproject.toml b/pyproject.toml index a934e74..58f5509 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -97,6 +97,10 @@ envs.hatch-test.overrides.matrix.deps.env-vars = [ envs.hatch-test.default-args = [] envs.hatch-test.dependency-groups = [ "dev", "test" ] +[tool.djlint] +indent = 2 +single_attribute_per_line = true + [tool.ruff] line-length = 120 src = [ "src" ] diff --git a/src/scverse_doc/theme/__init__.py b/src/scverse_doc/theme/__init__.py index be631cb..6337d01 100644 --- a/src/scverse_doc/theme/__init__.py +++ b/src/scverse_doc/theme/__init__.py @@ -114,6 +114,7 @@ def _add_ecosystem_context( def setup(app: Sphinx) -> ExtensionMetadata: """Register the theme, its templates, and the build hooks.""" app.add_html_theme("scverse", str(_THEME_PATH)) + app.add_js_file("js/readthedocs.js", type="module") app.config.templates_path = [*app.config.templates_path, str(_THEME_PATH / "components")] app.setup_extension("scverse_doc.source") diff --git a/src/scverse_doc/theme/scverse/components/scverse-ecosystem.html b/src/scverse_doc/theme/scverse/components/scverse-ecosystem.html index db83408..c0d5094 100644 --- a/src/scverse_doc/theme/scverse/components/scverse-ecosystem.html +++ b/src/scverse_doc/theme/scverse/components/scverse-ecosystem.html @@ -5,31 +5,31 @@ without any package touching its own conf.py. -#} {%- if theme_show_ecosystem_dropdown | tobool and scverse_ecosystem -%} -
- - -
+
+ + +
{%- endif -%} diff --git a/src/scverse_doc/theme/scverse/components/scverse-footer.html b/src/scverse_doc/theme/scverse/components/scverse-footer.html index 823cfe1..f1a5d26 100644 --- a/src/scverse_doc/theme/scverse/components/scverse-footer.html +++ b/src/scverse_doc/theme/scverse/components/scverse-footer.html @@ -1,20 +1,18 @@ {#- Shared footer: the boilerplate every scverse README already carries, rendered identically on every docs site. -#}
- - {%- if show_copyright and copyright %}© {{ copyright }}{% endif -%} - + {%- if show_copyright and copyright %}© {{ copyright }}{% endif -%} scverse is a NumFOCUS affiliated project. Governance - · + · Discourse - · + · Get involved {%- if last_updated %} - {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} + {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} {%- endif %}
diff --git a/src/scverse_doc/theme/scverse/layout.html b/src/scverse_doc/theme/scverse/layout.html new file mode 100644 index 0000000..4048c6e --- /dev/null +++ b/src/scverse_doc/theme/scverse/layout.html @@ -0,0 +1,5 @@ +{%- extends "pydata_sphinx_theme/layout.html" %} +{%- block extrahead %} + {{ super() }} + +{%- endblock %} diff --git a/src/scverse_doc/theme/scverse/static/js/readthedocs.js b/src/scverse_doc/theme/scverse/static/js/readthedocs.js new file mode 100644 index 0000000..d29411a --- /dev/null +++ b/src/scverse_doc/theme/scverse/static/js/readthedocs.js @@ -0,0 +1,30 @@ +// https://docs.readthedocs.com/platform/latest/addons.html#event-data-reference + +// Version Selector +document.addEventListener("readthedocs-addons-data-ready", (event) => { + const config = event.detail.data() + + const versionSelector = ` +
+ +
+ ` + + document + .querySelector("#pst-primary-sidebar") + .insertAdjacentHTML("beforeend", versionSelector) +}) diff --git a/src/scverse_doc/theme/scverse/theme.conf b/src/scverse_doc/theme/scverse/theme.conf deleted file mode 100644 index 09bb675..0000000 --- a/src/scverse_doc/theme/scverse/theme.conf +++ /dev/null @@ -1,26 +0,0 @@ -[theme] -inherit = pydata_sphinx_theme -stylesheet = styles/scverse.css -pygments_style = tango - -[options] -package = -accent = -show_ecosystem_dropdown = True - -navbar_align = left -navbar_start = navbar-logo -navbar_center = navbar-nav -navbar_end = scverse-ecosystem, theme-switcher, navbar-icon-links -navbar_persistent = search-button -secondary_sidebar_items = page-toc, edit-this-page, sourcelink -footer_start = scverse-footer -footer_center = -footer_end = -show_nav_level = 0 -show_toc_level = 2 -navigation_depth = 3 -collapse_navigation = False -pygments_light_style = tango -pygments_dark_style = monokai -announcement = https://scverse.org/announcement.html diff --git a/src/scverse_doc/theme/scverse/theme.toml b/src/scverse_doc/theme/scverse/theme.toml new file mode 100644 index 0000000..91c3369 --- /dev/null +++ b/src/scverse_doc/theme/scverse/theme.toml @@ -0,0 +1,27 @@ +[theme] +inherit = "pydata_sphinx_theme" +stylesheets = [ + "styles/scverse.css", +] +pygments_style = { default = "tango" } + +[options] +package = "" +accent = "" +show_ecosystem_dropdown = "True" +navbar_align = "left" +navbar_start = "navbar-logo" +navbar_center = "navbar-nav" +navbar_end = "scverse-ecosystem, theme-switcher, navbar-icon-links" +navbar_persistent = "search-button" +secondary_sidebar_items = "page-toc, edit-this-page, sourcelink" +footer_start = "scverse-footer" +footer_center = "" +footer_end = "" +show_nav_level = "0" +show_toc_level = "2" +navigation_depth = "3" +collapse_navigation = "False" +pygments_light_style = "tango" +pygments_dark_style = "monokai" +announcement = "https://scverse.org/announcement.html" From e56e51d20721f296a64cb772ecdc9f67cd816e77 Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Sun, 27 Sep 2026 21:42:28 +0200 Subject: [PATCH 02/10] add to sidebar? --- src/scverse_doc/theme/scverse/components/sidebar-versions.html | 1 + src/scverse_doc/theme/scverse/theme.toml | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 src/scverse_doc/theme/scverse/components/sidebar-versions.html diff --git a/src/scverse_doc/theme/scverse/components/sidebar-versions.html b/src/scverse_doc/theme/scverse/components/sidebar-versions.html new file mode 100644 index 0000000..bce238d --- /dev/null +++ b/src/scverse_doc/theme/scverse/components/sidebar-versions.html @@ -0,0 +1 @@ + diff --git a/src/scverse_doc/theme/scverse/theme.toml b/src/scverse_doc/theme/scverse/theme.toml index 91c3369..aeaa1fb 100644 --- a/src/scverse_doc/theme/scverse/theme.toml +++ b/src/scverse_doc/theme/scverse/theme.toml @@ -14,7 +14,8 @@ navbar_start = "navbar-logo" navbar_center = "navbar-nav" navbar_end = "scverse-ecosystem, theme-switcher, navbar-icon-links" navbar_persistent = "search-button" -secondary_sidebar_items = "page-toc, edit-this-page, sourcelink" +primary_sidebar_end = ["sidebar-ethical-ads", "sidebar-versions"] +secondary_sidebar_items = ["page-toc", "edit-this-page", "sourcelink"] footer_start = "scverse-footer" footer_center = "" footer_end = "" From 8328ed025563edb9d661415bd9764e5c0dfd934d Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Sun, 27 Sep 2026 21:55:45 +0200 Subject: [PATCH 03/10] some CSS --- src/scverse_doc/theme/__init__.py | 1 - .../theme/scverse/static/js/readthedocs.js | 30 ------------------- .../theme/scverse/static/styles/scverse.css | 14 +++++++++ 3 files changed, 14 insertions(+), 31 deletions(-) delete mode 100644 src/scverse_doc/theme/scverse/static/js/readthedocs.js diff --git a/src/scverse_doc/theme/__init__.py b/src/scverse_doc/theme/__init__.py index 6337d01..be631cb 100644 --- a/src/scverse_doc/theme/__init__.py +++ b/src/scverse_doc/theme/__init__.py @@ -114,7 +114,6 @@ def _add_ecosystem_context( def setup(app: Sphinx) -> ExtensionMetadata: """Register the theme, its templates, and the build hooks.""" app.add_html_theme("scverse", str(_THEME_PATH)) - app.add_js_file("js/readthedocs.js", type="module") app.config.templates_path = [*app.config.templates_path, str(_THEME_PATH / "components")] app.setup_extension("scverse_doc.source") diff --git a/src/scverse_doc/theme/scverse/static/js/readthedocs.js b/src/scverse_doc/theme/scverse/static/js/readthedocs.js deleted file mode 100644 index d29411a..0000000 --- a/src/scverse_doc/theme/scverse/static/js/readthedocs.js +++ /dev/null @@ -1,30 +0,0 @@ -// https://docs.readthedocs.com/platform/latest/addons.html#event-data-reference - -// Version Selector -document.addEventListener("readthedocs-addons-data-ready", (event) => { - const config = event.detail.data() - - const versionSelector = ` -
- -
- ` - - document - .querySelector("#pst-primary-sidebar") - .insertAdjacentHTML("beforeend", versionSelector) -}) diff --git a/src/scverse_doc/theme/scverse/static/styles/scverse.css b/src/scverse_doc/theme/scverse/static/styles/scverse.css index c06dc48..1e7372d 100644 --- a/src/scverse_doc/theme/scverse/static/styles/scverse.css +++ b/src/scverse_doc/theme/scverse/static/styles/scverse.css @@ -75,6 +75,20 @@ html { } } +/* --- Sidebar ------------------------------------------------------------ */ + +.sidebar-primary-item readthedocs-flyout { + --readthedocs-flyout-background-color: transparent; + --readthedocs-flyout-font-family: inherit; + --readthedocs-flyout-item-link-color: var(--pst-color-link); + --readthedocs-flyout-color: var(--scverse-color-text-muted); + --readthedocs-flyout-section-heading-color: var(--scverse-color-text-muted); + + .container { + position: static; + } +} + /* --- Cards -------------------------------------------------------------- */ /* .bd-content exists to beat sphinx-design in selector specificity */ From ae46530a6ba4bd40aa70eb2a4244d617b5694f51 Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Sun, 27 Sep 2026 22:12:54 +0200 Subject: [PATCH 04/10] no float --- .../theme/scverse/components/sidebar-versions.html | 6 +++++- src/scverse_doc/theme/scverse/static/styles/scverse.css | 4 ---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/scverse_doc/theme/scverse/components/sidebar-versions.html b/src/scverse_doc/theme/scverse/components/sidebar-versions.html index bce238d..f1bd674 100644 --- a/src/scverse_doc/theme/scverse/components/sidebar-versions.html +++ b/src/scverse_doc/theme/scverse/components/sidebar-versions.html @@ -1 +1,5 @@ - + + diff --git a/src/scverse_doc/theme/scverse/static/styles/scverse.css b/src/scverse_doc/theme/scverse/static/styles/scverse.css index 1e7372d..bd4f0f5 100644 --- a/src/scverse_doc/theme/scverse/static/styles/scverse.css +++ b/src/scverse_doc/theme/scverse/static/styles/scverse.css @@ -83,10 +83,6 @@ html { --readthedocs-flyout-item-link-color: var(--pst-color-link); --readthedocs-flyout-color: var(--scverse-color-text-muted); --readthedocs-flyout-section-heading-color: var(--scverse-color-text-muted); - - .container { - position: static; - } } /* --- Cards -------------------------------------------------------------- */ From 52e726d05de942287f2015fd039f4db9225a9afc Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Sun, 27 Sep 2026 22:19:32 +0200 Subject: [PATCH 05/10] format --- biome.jsonc | 7 +++++++ .../scverse/components/sidebar-versions.html | 19 ++++++++++++++++--- 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/biome.jsonc b/biome.jsonc index d7a7e97..fdb3aed 100644 --- a/biome.jsonc +++ b/biome.jsonc @@ -26,5 +26,12 @@ }, }, }, + // HTML formatting is opt-in; most templates contain Jinja inside tags, which Biome can't parse. + { + "includes": [ + "src/scverse_doc/theme/scverse/components/sidebar-versions.html", + ], + "html": { "formatter": { "enabled": true } }, + }, ], } diff --git a/src/scverse_doc/theme/scverse/components/sidebar-versions.html b/src/scverse_doc/theme/scverse/components/sidebar-versions.html index f1bd674..312c483 100644 --- a/src/scverse_doc/theme/scverse/components/sidebar-versions.html +++ b/src/scverse_doc/theme/scverse/components/sidebar-versions.html @@ -1,5 +1,18 @@ - From b1af30f7fec591df462fa17edddc159fae5b9647 Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Sun, 27 Sep 2026 22:25:51 +0200 Subject: [PATCH 06/10] more colors --- src/scverse_doc/theme/scverse/static/styles/scverse.css | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/scverse_doc/theme/scverse/static/styles/scverse.css b/src/scverse_doc/theme/scverse/static/styles/scverse.css index bd4f0f5..d8cf2a1 100644 --- a/src/scverse_doc/theme/scverse/static/styles/scverse.css +++ b/src/scverse_doc/theme/scverse/static/styles/scverse.css @@ -80,9 +80,11 @@ html { .sidebar-primary-item readthedocs-flyout { --readthedocs-flyout-background-color: transparent; --readthedocs-flyout-font-family: inherit; - --readthedocs-flyout-item-link-color: var(--pst-color-link); + --readthedocs-flyout-divider-color: var(--scverse-color-border); --readthedocs-flyout-color: var(--scverse-color-text-muted); --readthedocs-flyout-section-heading-color: var(--scverse-color-text-muted); + --readthedocs-flyout-link-color: var(--pst-color-link); + --readthedocs-flyout-item-link-color: var(--pst-color-link); } /* --- Cards -------------------------------------------------------------- */ From 1e54934c94df274bdcc190eced82806de31ce609 Mon Sep 17 00:00:00 2001 From: Phil Schaf Date: Mon, 28 Sep 2026 16:10:42 +0200 Subject: [PATCH 07/10] update link color --- src/scverse_doc/theme/scverse/static/styles/scverse.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/scverse_doc/theme/scverse/static/styles/scverse.css b/src/scverse_doc/theme/scverse/static/styles/scverse.css index 922912f..67e83ce 100644 --- a/src/scverse_doc/theme/scverse/static/styles/scverse.css +++ b/src/scverse_doc/theme/scverse/static/styles/scverse.css @@ -115,7 +115,7 @@ html { --readthedocs-flyout-divider-color: var(--scverse-color-border); --readthedocs-flyout-color: var(--scverse-color-text-muted); --readthedocs-flyout-section-heading-color: var(--scverse-color-text-muted); - --readthedocs-flyout-link-color: var(--pst-color-link); + --readthedocs-flyout-link-color: var(--pst-color-link-higher-contrast); --readthedocs-flyout-item-link-color: var(--pst-color-link); } From 01d58443ce048d6d182103f097cf65313c56c926 Mon Sep 17 00:00:00 2001 From: Phil Schaf Date: Mon, 28 Sep 2026 16:17:19 +0200 Subject: [PATCH 08/10] fix RTD icon --- .../theme/scverse/components/sidebar-versions.html | 10 ++++++---- .../theme/scverse/static/styles/scverse.css | 2 ++ 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/src/scverse_doc/theme/scverse/components/sidebar-versions.html b/src/scverse_doc/theme/scverse/components/sidebar-versions.html index 312c483..3e059c2 100644 --- a/src/scverse_doc/theme/scverse/components/sidebar-versions.html +++ b/src/scverse_doc/theme/scverse/components/sidebar-versions.html @@ -1,11 +1,13 @@