From 6b5bf39779e7e19fa7a243d209ba9072bbc75435 Mon Sep 17 00:00:00 2001
From: Yixing Lao <yixing.lao@gmail.com>
Date: Sat, 11 Jan 2025 20:05:17 +0800
Subject: [PATCH] docs(conf.py): improve version detection logic and logging
 for documentation builds

- Clarify comments and variable names for better readability
- Add explicit version tag matching logic to determine if a commit is version-tagged
- Enhance logging messages to provide more detailed and accurate information about the build context
- Handle git information detection errors with a more descriptive message
---
 docs/conf.py | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 3bf00dd..3d0986d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,7 +18,7 @@
 # Get version from camtools package
 version = ct.__version__
 
-# When building a tagged commit, only use the tag as "release". Otherwise,
+# 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:
@@ -39,20 +39,24 @@
         .strip()
         .split()
     )
-    print(f"- Version         : {version}")
+    print(f"- Package version : {version}")
     print(f"- Git hash        : {git_hash}")
     print(f"- All tags        : {all_tags}")
     print(f"- HEAD tags       : {head_tags}")
 
-    if not 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} (untagged commit)")
+        print(f"- Docs version    : {release} (not a version tagged commit)")
     else:
         release = version
-        print(f"- Docs version    : {release} (tagged commit)")
+        print(f"- Docs version    : {release} (version tagged as {version_tag})")
 except subprocess.CalledProcessError:
     release = version
-    print(f"- Docs version    : {release} (cannot detect tags)")
+    print(f"- Docs version    : {release} (cannot detect git information)")
 
 project = "CamTools"
 copyright = "2024, Yixing Lao"