docs(sphinx): render version + add home to sidebar (#34)

sphinx_rtd_theme >=3.0 dropped the `display_version` option, so the
previous setting in conf.py was a no-op. Override the upstream
`sidebartitle` block to render `{{ version }}` between the project link
and the search box, and add a matching `.version` style.

Also add a `Home <self>` toctree entry so the landing page is reachable
from the sidebar, and prefix each entry with a small emoji.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: AndreFCruz

docs/_static/custom.css

@@ -0,0 +1,11 @@
+/* Version label rendered by docs/_templates/layout.html under the project
+   title in the sidebar. sphinx_rtd_theme >=3.0 no longer ships a `.version`
+   style, so we provide one matching the prior look. */
+.wy-side-nav-search > .version {
+    color: rgba(255, 255, 255, 0.45);
+    font-size: 90%;
+    margin-top: -0.4045em;
+    margin-bottom: 0.809em;
+    font-weight: normal;
+    display: block;
+}

docs/_templates/layout.html

@@ -0,0 +1,32 @@
+{# sphinx_rtd_theme >=3.0 dropped the `display_version` switch from its sidebar
+   template. We re-add a small version line under the project title by
+   overriding the upstream `sidebartitle` block. The body mirrors the upstream
+   block (sphinx_rtd_theme/layout.html) so we can slot in the `.version` div
+   between the project link and the searchbox. #}
+{% extends "!layout.html" %}
+
+{% block sidebartitle %}
+  {%- set _logo_url = logo_url|default(pathto('_static/' + (logo or ""), 1)) %}
+  {%- set _root_doc = root_doc|default(master_doc) %}
+  <a href="{{ pathto(_root_doc) }}"{% if not theme_logo_only %} class="icon icon-home"{% endif %}>
+    {% if not theme_logo_only %}{{ project }}{% endif %}
+    {%- if logo or logo_url %}
+      <img src="{{ _logo_url }}" class="logo" alt="{{ _('Logo') }}"/>
+    {%- endif %}
+  </a>
+
+  {%- if version %}
+    <div class="version">{{ version }}</div>
+  {%- endif %}
+
+  {%- if READTHEDOCS or DEBUG %}
+    {%- if theme_version_selector or theme_language_selector %}
+      <div class="switch-menus">
+        <div class="version-switch"></div>
+        <div class="language-switch"></div>
+      </div>
+    {%- endif %}
+  {%- endif %}
+
+  {%- include "searchbox.html" %}
+{% endblock %}

docs/conf.py

@@ -61,13 +61,13 @@
 html_js_files = [
     'custom.js',    # custom JS file
 ]
+html_css_files = [
+    'custom.css',   # custom CSS file
+]
 
-# Show the package version in the sidebar header (under the project title).
-# `release` (set above) is the source; `display_version=True` is the
-# sphinx_rtd_theme switch that renders it.
-html_theme_options = {
-    'display_version': True,
-}
+# The package version is rendered under the project title in the sidebar via
+# `_templates/layout.html`, which overrides sphinx_rtd_theme's `sidebartitle`
+# block. The theme's old `display_version` option was removed in 3.0.
 
 # nbsphinx configuration
 nbsphinx_execute = 'never'  # Set to 'always' if you want to execute the notebooks during the build process

docs/index.rst

@@ -33,10 +33,11 @@ Check out the following sub-pages:
 .. toctree::
    :maxdepth: 1
 
-   Readme file <readme>
-   Updates <updates>
-   API reference <source/modules>
-   Example notebooks <notebooks>
+   🏠 Home <self>
+   📖 Readme file <readme>
+   📝 Updates <updates>
+   ⚙️ API reference <source/modules>
+   📓 Example notebooks <notebooks>
 
 
 Citing