docs(conf.py): improve version detection logic for documentation buil…

…ds by checking if the current commit is version-tagged and using version+git hash only for non-tagged commits

docs/conf.py

@@ -18,16 +18,47 @@
 # Get version from camtools package
 version = ct.__version__
 
-# Get git commit hash
+# When building a version-tagged commit, only use the version 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}")
+
+    # Check if any HEAD tag matches the version pattern
+    version_tag = f"v{version}"
+    is_version_tagged = version_tag in head_tags
+
+    if not is_version_tagged:
+        release = f"{version}+{git_hash}"
+        print(f"- Docs version  : {release} (not a version tagged commit)")
+    else:
+        release = version
+        print(
+            f"- Docs version: {release} ({git_hash} is version tagged as {version_tag})"
+        )
 except subprocess.CalledProcessError:
     release = version
+    print(f"- Docs version  : {release} (cannot detect git information)")
 
 project = "CamTools"
 copyright = "2024, Yixing Lao"