From 07b38a9e3b4753f00f02f10229dcf1e9ce7b3615 Mon Sep 17 00:00:00 2001
From: Yixing Lao <yixing.lao@gmail.com>
Date: Sat, 11 Jan 2025 20:15:26 +0800
Subject: [PATCH] docs(conf.py): enhance version detection logic to
 differentiate between version-tagged and untagged commits

The commit improves the version detection mechanism in the documentation configuration. It now checks if the current commit is tagged with a version and uses the version number directly for tagged commits. For untagged commits, it appends the git hash to the version number. This ensures more accurate versioning in the documentation build process.
---
 docs/conf.py | 33 +++++++++++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 7e71d2bb..292a3534 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,16 +18,45 @@
 # 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 current commit has a version tag
+    if f"v{version}" in head_tags:
+        release = version
+        status = f"(commit {git_hash} is version tagged as v{version})"
+    else:
+        release = f"{version}+{git_hash}"
+        status = f"(commit {git_hash} is not version tagged)"
+    print(f"- Docs version: {release} {status}")
+
 except subprocess.CalledProcessError:
     release = version
+    print(f"- Docs version  : {release} (cannot detect git information)")
 
 project = "CamTools"
 copyright = "2024, Yixing Lao"