docs(conf.py): improve version detection logic and logging for docume…

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

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