docs(conf.py): improve version detection logic for tagged and untagge…

…d 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

@@ -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"