Add the version string to the sidebar in the HTML docs (#95)

* Add the version string to the sidebar in the HTML docs

This is useful because Read the Docs doesn't show the current version
for "latest" or "stable". Having the exact version, down to commit, etc.
is useful!

* Pin Furo to ensure compatibility of custom CSS & templates

Author: lagru

docs/conf.py

@@ -3,10 +3,17 @@
 
 from datetime import date
 
+import setuptools_scm
+
 # -- Project information ------------------------------------------------------
 
 project = "docstub"
-copyright = f"{date.today().year}, docstub contributors"
+
+version = setuptools_scm.get_version(search_parent_directories=True)
+version = f"v{version}"
+version = version.replace("+", "<wbr>+")  # Insert wrapping hint for long dev version
+
+copyright = f"{date.today().year} docstub contributors."
 
 templates_path = ["templates"]
 
@@ -62,6 +69,7 @@
 html_sidebars = {
     "**": [
         "sidebar/brand.html",
+        "version.html",
         "sidebar/search.html",
         "sidebar/scroll-start.html",
         "sidebar/navigation.html",

docs/static/furo_overrides.css

@@ -8,6 +8,29 @@ article .align-default {
     margin-right: unset;
 }
 
+/* Apply the same padding to the ad as other items in the sidebar */
 .ethical-ad-padding {
     padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);
 }
+
+/* Account for margin-bottom of a preceeding sidebar-tree's to keep spacing
+   between items consistent. */
+.sidebar-tree + .sidebar-tree {
+    margin-top: calc(var(--sidebar-tree-space-above) - var(--sidebar-item-spacing-vertical));
+}
+
+/* Style and align inserted version in sidebar. */
+.sidebar-version {
+    font-family: var(--font-stack--monospace);
+    font-size: var(--font-size--small);
+    color: var(--color-foreground-secondary);
+    padding-inline: var(--sidebar-item-spacing-horizontal);
+    padding-bottom: var(--sidebar-item-spacing-vertical) ;
+    margin-bottom: var(--sidebar-item-spacing-vertical);
+    overflow-wrap: break-word;
+}
+/* Remove bottom margin of brand so that version info is closer and better aligned. */
+.sidebar-brand-text {
+    margin-bottom: 0;
+
+}

docs/templates/ethical-ads.html

@@ -1,3 +1,5 @@
+{#- Indicate ad placement to Read the Docs. -#}
+
 <div class="sidebar-tree ethical-ad-padding">
   <div id="ethical-ad-placement"></div>
 </div>

docs/templates/external-links.html

@@ -1,3 +1,5 @@
+{#- Insert external project links into the sidebar. -#}
+
 <div class="sidebar-tree">
   <p class="caption" role="heading"><span class="caption-text">Links</span></p>
   <ul>

docs/templates/version.html

@@ -0,0 +1,7 @@
+{#- Insert version information into the sidebar. -#}
+
+{% if version %}
+<div class="sidebar-version">
+  <span>{{ version }}</span>
+</div>
+{%- endif %}

pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=61", "setuptools_scm[toml]>=7"]
+requires = ["setuptools>=61", "setuptools-scm[simple]>=8"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -57,10 +57,11 @@ test = [
 ]
 docs = [
     "sphinx",
-    "furo",
+    "furo ==2025.9.25",
     "numpydoc",
     "myst-parser",
     "sphinx-copybutton",
+    "setuptools-scm[simple] >=8"
 ]
 dev = [
     {include-group = "test"},