From 73844f758fb22965ff0bb8b694abaaed0c4e0c76 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Thu, 23 Oct 2025 22:24:01 +0200
Subject: [PATCH 1/2] 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!
---
 docs/conf.py                       | 10 +++++++++-
 docs/static/furo_overrides.css     | 23 +++++++++++++++++++++++
 docs/templates/ethical-ads.html    |  2 ++
 docs/templates/external-links.html |  2 ++
 docs/templates/version.html        |  7 +++++++
 pyproject.toml                     |  3 ++-
 6 files changed, 45 insertions(+), 2 deletions(-)
 create mode 100644 docs/templates/version.html

diff --git a/docs/conf.py b/docs/conf.py
index a32d735..1b93b9a 100644
--- a/docs/conf.py
+++ b/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",
diff --git a/docs/static/furo_overrides.css b/docs/static/furo_overrides.css
index 3a93e66..2d5dd17 100644
--- a/docs/static/furo_overrides.css
+++ b/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;
+
+}
\ No newline at end of file
diff --git a/docs/templates/ethical-ads.html b/docs/templates/ethical-ads.html
index d484c3d..5c813f5 100644
--- a/docs/templates/ethical-ads.html
+++ b/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>
\ No newline at end of file
diff --git a/docs/templates/external-links.html b/docs/templates/external-links.html
index 54dd0ea..3e691b5 100644
--- a/docs/templates/external-links.html
+++ b/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>
diff --git a/docs/templates/version.html b/docs/templates/version.html
new file mode 100644
index 0000000..8cbc56f
--- /dev/null
+++ b/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 %}
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index 428fcbc..2e32b31 100644
--- a/pyproject.toml
+++ b/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]
@@ -61,6 +61,7 @@ docs = [
     "numpydoc",
     "myst-parser",
     "sphinx-copybutton",
+    "setuptools-scm[simple] >=8"
 ]
 dev = [
     {include-group = "test"},

From 1ed8bd21d04f329cc1f4ba5eb52ec64a485c85b4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Thu, 23 Oct 2025 22:26:54 +0200
Subject: [PATCH 2/2] Pin Furo to ensure compatibility of custom CSS &
 templates

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 2e32b31..953ec88 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -57,7 +57,7 @@ test = [
 ]
 docs = [
     "sphinx",
-    "furo",
+    "furo ==2025.9.25",
     "numpydoc",
     "myst-parser",
     "sphinx-copybutton",