feat: RTD version selector

.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:

biome.jsonc

@@ -10,6 +10,11 @@
         ],
     },
     "formatter": { "useEditorconfig": true },
+    "javascript": {
+        "formatter": {
+            "semicolons": "asNeeded",
+        },
+    },
     "overrides": [
         {
             "includes": ["./.vscode/*.json", "**/*.jsonc"],
@@ -21,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 } },
+        },
     ],
 }

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" ]

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 -%}
-<div class="dropdown scverse-ecosystem-dropdown">
-  <button
-    class="btn dropdown-toggle nav-link"
-    type="button"
-    data-bs-toggle="dropdown"
-    aria-expanded="false"
-    aria-label="{{ _('scverse packages') }}"
-  >
-    {{ _("scverse packages") }}
-  </button>
-  <ul class="dropdown-menu dropdown-menu-end">
-    {%- for group, label in [("core", _("Core")), ("ecosystem", _("Ecosystem"))] %}
-    {%- if scverse_ecosystem[group] %}
-    <li><h6 class="dropdown-header">{{ label }}</h6></li>
-    {%- for pkg in scverse_ecosystem[group] %}
-    <li>
-      <a
-        class="dropdown-item{% if pkg.current %} active{% endif %}"
-        href="{{ pkg.docs }}"
-        {% if pkg.current %}aria-current="page"{% endif %}
-      >{{ pkg.name }}</a>
-    </li>
-    {%- endfor %}
-    {%- endif %}
-    {%- endfor %}
-  </ul>
-</div>
+  <div class="dropdown scverse-ecosystem-dropdown">
+    <button
+      class="btn dropdown-toggle nav-link"
+      type="button"
+      data-bs-toggle="dropdown"
+      aria-expanded="false"
+      aria-label="{{ _("scverse packages") }}"
+    >{{ _("scverse packages") }}</button>
+    <ul class="dropdown-menu dropdown-menu-end">
+      {%- for group, label in [("core", _("Core")), ("ecosystem", _("Ecosystem"))] %}
+        {%- if scverse_ecosystem[group] %}
+          <li>
+            <h6 class="dropdown-header">{{ label }}</h6>
+          </li>
+          {%- for pkg in scverse_ecosystem[group] %}
+            <li>
+              <a
+                class="dropdown-item{% if pkg.current %} active{% endif %}"
+                href="{{ pkg.docs }}"
+                {% if pkg.current %}aria-current="page"{% endif %}
+              >{{ pkg.name }}</a>
+            </li>
+          {%- endfor %}
+        {%- endif %}
+      {%- endfor %}
+    </ul>
+  </div>
 {%- endif -%}

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. -#}
 <div class="scverse-footer-brand">
-  <span>
-    {%- if show_copyright and copyright %}&copy; {{ copyright }}{% endif -%}
-  </span>
+  <span>{%- if show_copyright and copyright %}© {{ copyright }}{% endif -%}</span>
   <span>
     <a href="https://scverse.org/">scverse</a> is a
     <a href="https://numfocus.org/">NumFOCUS</a> affiliated project.
   </span>
   <span>
     <a href="https://scverse.org/about/roles/">Governance</a>
-    &middot;
+    ·
     <a href="https://discourse.scverse.org/">Discourse</a>
-    &middot;
+    ·
     <a href="https://scverse.org/join/">Get involved</a>
   </span>
   {%- if last_updated %}
-  <span>{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}</span>
+    <span>{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}</span>
   {%- endif %}
 </div>

src/scverse_doc/theme/scverse/components/sidebar-versions.html

@@ -0,0 +1,20 @@
+<readthedocs-flyout></readthedocs-flyout>
+<script type="module">
+// flyout.css hardcodes `.container { position: fixed }` with no part/variable to override it,
+// and the logo is an <img> of a #fcfcfc SVG (made for dark backgrounds): dim it to the grey RTD uses for its icons
+customElements.whenDefined("readthedocs-flyout").then(() => {
+    const sheet = new CSSStyleSheet()
+    sheet.replaceSync(`
+        .container { position: static; max-width: none; max-height: none; }
+        header > img.logo { filter: brightness(0.5); }
+    `)
+    for (const { shadowRoot } of document.querySelectorAll(
+        "readthedocs-flyout",
+    )) {
+        shadowRoot.adoptedStyleSheets = [
+            ...shadowRoot.adoptedStyleSheets,
+            sheet,
+        ]
+    }
+})
+</script>

src/scverse_doc/theme/scverse/layout.html

@@ -0,0 +1,5 @@
+{%- extends "pydata_sphinx_theme/layout.html" %}
+{%- block extrahead %}
+  {{ super() }}
+  <meta name="readthedocs-addons-api-version" content="1" />
+{%- endblock %}

src/scverse_doc/theme/scverse/static/styles/scverse.css

@@ -107,6 +107,29 @@ html {
     }
 }
 
+/* --- Sidebar ------------------------------------------------------------ */
+
+/* pydata hides the sidebar when it has no toctree (e.g. the root page), but the version selector should stay */
+@media (min-width: 960px) {
+    .bd-sidebar-primary.hide-on-wide:has(readthedocs-flyout) {
+        display: flex;
+    }
+}
+.sidebar-primary-item:has(> :only-child:empty) {
+    display: none;
+}
+.sidebar-primary-item readthedocs-flyout {
+    --readthedocs-flyout-background-color: transparent;
+    --readthedocs-flyout-font-family: inherit;
+    --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-higher-contrast);
+    --readthedocs-flyout-item-link-color: var(--pst-color-link);
+
+    padding: 0;
+}
+
 /* --- Cards -------------------------------------------------------------- */
 
 /* .bd-content exists to beat sphinx-design in selector specificity */

src/scverse_doc/theme/scverse/theme.toml

@@ -0,0 +1,28 @@
+[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"
+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 = ""
+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"