From e7e6f7d1fc05c5d9fd49316ac036f52b3e9f8985 Mon Sep 17 00:00:00 2001
From: Yixing Lao <yixing.lao@gmail.com>
Date: Sat, 11 Jan 2025 19:59:26 +0800
Subject: [PATCH] docs(conf.py): improve version detection logic for tagged and
 untagged commits

The commit enhances the version detection logic in `conf.py` to differentiate between tagged and untagged commits. For tagged commits, the version is used directly as the release. For untagged commits, the version is appended with the git hash. This ensures more accurate versioning in documentation builds. Debugging prints are added to log the detected version, git hash, and tags for clarity.
---
 docs/conf.py | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 7e71d2bb..3bf00dd4 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,16 +18,41 @@
 # Get version from camtools package
 version = ct.__version__
 
-# Get git commit hash
+# When building a tagged commit, only use the tag as "release". Otherwise,
+# use the version number and the git hash as "release".
+print("[Detecting docs version]")
 try:
     git_hash = (
         subprocess.check_output(["git", "rev-parse", "--short", "HEAD"])
         .decode("ascii")
         .strip()
     )
-    release = f"{version}+{git_hash}"
+    all_tags = (
+        subprocess.check_output(["git", "tag", "--list"])
+        .decode("ascii")
+        .strip()
+        .split()
+    )
+    head_tags = (
+        subprocess.check_output(["git", "tag", "--points-at", "HEAD"])
+        .decode("ascii")
+        .strip()
+        .split()
+    )
+    print(f"- Version         : {version}")
+    print(f"- Git hash        : {git_hash}")
+    print(f"- All tags        : {all_tags}")
+    print(f"- HEAD tags       : {head_tags}")
+
+    if not head_tags:
+        release = f"{version}+{git_hash}"
+        print(f"- Docs version    : {release} (untagged commit)")
+    else:
+        release = version
+        print(f"- Docs version    : {release} (tagged commit)")
 except subprocess.CalledProcessError:
     release = version
+    print(f"- Docs version    : {release} (cannot detect tags)")
 
 project = "CamTools"
 copyright = "2024, Yixing Lao"