From 9d12937495ab3944b0a9ffa21a82eb71537ce908 Mon Sep 17 00:00:00 2001
From: energyscholar <energyscholar@gmail.com>
Date: Thu, 30 Jul 2026 13:09:46 -0700
Subject: [PATCH] Derive the docs version instead of hardcoding it

docs/source/conf.py had to be bumped by hand, so it drifted: it still read
2.1.1 while the package was on 2.1.3. It went unnoticed because only `version`
was set, and the RTD theme renders `release` -- so the wrong value was never
displayed anywhere a reader would see it.

Resolve the version from installed package metadata first, since that is how
the docs are actually built (.readthedocs.yaml installs the package, and so
does CI), falling back to pyproject.toml for a tree where the package is not
installed, and finally to a literal. The resolver cannot raise: fail_on_warning
is set, so an exception here would take the whole build down.

Set `release` as well as `version`, so the number is actually rendered. The
page title changes from "ewstools documentation" to "ewstools 2.1.3
documentation".
---
 docs/source/conf.py | 40 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 3ba7567..e192be6 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -24,8 +24,44 @@
 copyright = "2022, Thomas M Bury"
 author = "Thomas M Bury"
 
-# Semantic version number
-version = "2.1.1"
+# Semantic version number.
+#
+# Derived, never hardcoded. This line had to be bumped by hand, so it drifted:
+# it still read 2.1.1 while the package was on 2.1.3.
+#
+# Resolution order: installed package metadata first, because that is how the
+# docs are actually built (.readthedocs.yaml installs the package, and so does
+# CI); then pyproject.toml, for a build tree where the package is not installed;
+# then a literal fallback.
+#
+# This must not raise under any circumstances: .readthedocs.yaml sets
+# `sphinx.fail_on_warning`, so an exception here takes the whole build down.
+def _resolve_version():
+    try:
+        from importlib.metadata import version as _installed_version
+
+        return _installed_version("ewstools")
+    except Exception:
+        pass
+    try:
+        import tomllib  # standard library on Python 3.11+ only
+
+        _pyproject = os.path.join(
+            os.path.dirname(os.path.abspath(__file__)), "..", "..", "pyproject.toml"
+        )
+        with open(_pyproject, "rb") as _f:
+            return tomllib.load(_f)["project"]["version"]
+    except Exception:
+        pass
+    return "unknown"
+
+
+version = _resolve_version()
+
+# The sphinx_rtd_theme displays `release`, not `version`. Leaving `release`
+# unset is why the stale value above went unnoticed across two releases: it was
+# wrong, but it was never rendered anywhere a reader would see it.
+release = version
 
 # -- General configuration ---------------------------------------------------