Review comments

Author: sankalps0549

README.md

@@ -68,7 +68,7 @@ python run.py build
 python run.py build-docs
 ```
 
-The documentation version switcher (`switcher.json`) is automatically generated from git tags during the build process. Only tagged versions are included by default to ensure all links work correctly.
+The documentation version switcher (`switcher.json`) is automatically generated from git tags matching the `vX.Y.Z` format during the build process. Only tagged versions are included by default to ensure all links work correctly.
 
 Options:
 - `--skip-build` (`-s`): Skip building before generating docs
@@ -118,11 +118,11 @@ python -m http.server 8000
 Then open http://localhost:8000 in your browser. The root automatically redirects to the latest version documentation.
 
 **Versioned Documentation:**
-- Each git tag creates a separate documentation version (e.g., `/v26.0.5/`)
+- Each git tag matching `vX.Y.Z` creates a separate documentation version (e.g., `/v26.0.5/`)
 - A `/latest/` directory points to the newest version
 - Root (`/`) automatically redirects to `/latest/`
 - Run `git fetch --tags` before building to ensure all version tags are available
-- If no version tags (tags starting with `v`) are found in the repository, the build automatically falls back to a single-version Sphinx build instead of attempting the multi-version build
+- If no version tags matching `vX.Y.Z` are found in the repository, the build automatically falls back to a single-version Sphinx build instead of attempting the multi-version build
 
 ### Running the Formatter
 

docs/source/conf.py

@@ -34,7 +34,7 @@
 ]
 
 templates_path = ['_templates']
-smv_tag_whitelist = r'^v?\d+\.\d+\.\d+$'
+smv_tag_whitelist = r'^v\d+\.\d+\.\d+$'
 smv_branch_whitelist = r'^$'
 smv_remote_whitelist = r'^origin$'
 smv_latest_version = 'latest'

docs/source/readme.rst

@@ -1254,8 +1254,9 @@ The project includes a ``run.py`` script with several useful commands:
 - ``python run.py test`` - Run tests
 - ``python run.py lint`` - Run code linting
 - ``python run.py format`` - Format code with black
-- ``python run.py build-docs`` - Build versioned documentation (HTML uses git tags for the
-  navigation dropdown; run ``git fetch --tags`` locally before building)
+- ``python run.py build-docs`` - Build versioned documentation (HTML uses git tags matching
+  ``vX.Y.Z`` for the navigation dropdown; run ``git fetch --tags`` locally before building).
+  Falls back to a single-version build when no matching version tags are found.
 
   - ``--skip-build`` (``-s``): Skip building the package before generating docs
   - ``--local`` (``-l``): Build documentation locally for a single version (skips multi-version build)
@@ -1265,9 +1266,9 @@ The project includes a ``run.py`` script with several useful commands:
 
 .. note::
    The documentation version switcher (``switcher.json``) is automatically generated from
-   git tags during the build process. Only tagged versions are included to ensure all
-   documentation links work correctly. If ``version.json`` is newer than the latest tag,
-   create a git tag to include it in the version switcher.
+   git tags matching the ``vX.Y.Z`` format during the build process. Only tagged versions
+   are included to ensure all documentation links work correctly. If ``version.json`` is
+   newer than the latest tag, create a git tag to include it in the version switcher.
 
 **Incremental Builds for Development:**
 
@@ -1296,11 +1297,11 @@ Then open http://localhost:8000 in your browser.
 
 **Versioned Documentation Features:**
 
-- Each git tag creates a separate documentation version (e.g., ``/v26.0.5/``)
+- Each git tag matching ``vX.Y.Z`` creates a separate documentation version (e.g., ``/v26.0.5/``)
 - A ``/latest/`` directory points to the newest version (symlink on Unix, copy on Windows)
 - Root (``/``) automatically redirects to ``/latest/`` for convenience
 - Version switcher dropdown in the navigation bar allows switching between versions
-- If no version tags (tags starting with ``v``) are found in the repository, the build
+- If no version tags matching ``vX.Y.Z`` are found in the repository, the build
   automatically falls back to a single-version Sphinx build instead of attempting the
   multi-version build
 

run.py

@@ -28,7 +28,7 @@
     build-docs                      Build the documentation.
     format                          Format all Python files in the repository using black.
     generate-expected-data          Generate expected data for integration tests.
-    generate-switcher               Generate switcher.json from git tags.
+    generate-switcher               Generate switcher.json from git tags (vX.Y.Z format).
     install                         Install the moldflow-api package.
     install-package-requirements    Install package dependencies.
     lint                            Lint all Python files in the repository.
@@ -67,6 +67,7 @@
 """
 
 import os
+import re
 import sys
 import json
 import logging
@@ -118,6 +119,14 @@
 PYTHON_FILES = [MOLDFLOW_DIR, DOCS_SOURCE_DIR, TEST_DIR, "run.py"]
 SWITCHER_JSON = os.path.join(DOCS_STATIC_DIR, 'switcher.json')
 
+# Must match smv_tag_whitelist in docs/source/conf.py
+VERSION_TAG_RE = re.compile(r'^v\d+\.\d+\.\d+$')
+
+
+def _is_version_tag(name):
+    """Return True if *name* matches the vX.Y.Z version tag format."""
+    return VERSION_TAG_RE.match(name) is not None
+
 
 def run_command(args, cwd=os.getcwd(), extra_env=None):
     """Runs native executable command, args is an array of strings"""
@@ -367,7 +376,7 @@ def create_root_redirect(build_output: str) -> None:
 
 def create_latest_alias(build_output: str) -> None:
     """Create a 'latest' alias pointing to the newest version using symlinks when possible."""
-    version_dirs = [d for d in os.listdir(build_output) if d.startswith('v')]
+    version_dirs = [d for d in os.listdir(build_output) if _is_version_tag(d)]
     if not version_dirs:
         return
 
@@ -429,9 +438,9 @@ def _build_html_docs_full(build_output, skip_switcher, include_current):
             "Failed to build documentation with "
             "sphinx_multiversion.\n"
             "This can happen if no Git tags or branches match "
-            "your version pattern.\n"
+            "the required vX.Y.Z version pattern.\n"
             "Try running 'git fetch --tags' and ensure version "
-            "tags exist in the repo.\n"
+            "tags (e.g. v1.2.3) exist in the repo.\n"
             "Underlying error: %s",
             str(err),
         )
@@ -445,11 +454,11 @@ def _get_missing_version_tags(build_output):
     if os.path.exists(build_output):
         for item in os.listdir(build_output):
             item_path = os.path.join(build_output, item)
-            if os.path.isdir(item_path) and item.startswith('v'):
+            if os.path.isdir(item_path) and _is_version_tag(item):
                 if item != 'latest':
                     existing_versions.add(item)
 
-    all_tags = {tag.name for tag in GIT_REPO.tags if tag.name.startswith('v')}
+    all_tags = {tag.name for tag in GIT_REPO.tags if _is_version_tag(tag.name)}
 
     missing = list(all_tags - existing_versions)
 
@@ -570,11 +579,14 @@ def _run_sphinx_build(target):
     )
 
 
-def _remove_stale_switcher():
-    """Remove any leftover switcher.json so a single-version build doesn't ship stale data."""
+def _clean_stale_docs():
+    """Remove stale switcher.json from the source tree and wipe the build directory."""
     if os.path.exists(SWITCHER_JSON):
         os.remove(SWITCHER_JSON)
         logging.info('Removed stale %s', SWITCHER_JSON)
+    if os.path.exists(DOCS_BUILD_DIR):
+        logging.info('Removing stale build directory %s', DOCS_BUILD_DIR)
+        shutil.rmtree(DOCS_BUILD_DIR)
 
 
 # pylint: disable=R0912
@@ -590,13 +602,12 @@ def build_docs(
 
     if not incremental:
         logging.info('Removing existing Sphinx documentation...')
-        if os.path.exists(DOCS_BUILD_DIR):
-            shutil.rmtree(DOCS_BUILD_DIR)
+        _clean_stale_docs()
     else:
         logging.info('Incremental build mode: preserving existing documentation...')
 
     try:
-        has_version_tags = any(tag.name.startswith('v') for tag in GIT_REPO.tags)
+        has_version_tags = any(_is_version_tag(tag.name) for tag in GIT_REPO.tags)
 
         if target == 'html' and not local and has_version_tags:
             build_output = os.path.join(DOCS_BUILD_DIR, 'html')
@@ -610,21 +621,21 @@ def build_docs(
             create_root_redirect(build_output)
         elif target == 'html' and not local and not has_version_tags:
             logging.warning(
-                'No version tags starting with \'v\' found in the repository. '
+                'No version tags matching vX.Y.Z found in the repository. '
                 'Falling back to a single-version documentation build.'
             )
-            _remove_stale_switcher()
+            _clean_stale_docs()
             _run_sphinx_build(target)
         else:
             if target == 'html' and not skip_switcher:
                 if has_version_tags:
                     generate_switcher(include_current=include_current)
                 else:
                     logging.warning(
-                        'No version tags starting with \'v\' found in the repository. '
+                        'No version tags matching vX.Y.Z found in the repository. '
                         'Skipping switcher.json generation.'
                     )
-                    _remove_stale_switcher()
+                    _clean_stale_docs()
             _run_sphinx_build(target)
         logging.info('Sphinx documentation built successfully.')
     except Exception as err:
@@ -876,7 +887,7 @@ def _get_current_version_if_newer():
         )
 
         # Get latest git tag
-        tags = [tag.name for tag in GIT_REPO.tags if tag.name.startswith('v')]
+        tags = [tag.name for tag in GIT_REPO.tags if _is_version_tag(tag.name)]
 
         if not tags:
             return None
@@ -898,8 +909,8 @@ def _get_current_version_if_newer():
 
 
 def generate_switcher(include_current=False):
-    """Generate switcher.json from git tags"""
-    logging.info('Generating switcher.json from git tags')
+    """Generate switcher.json from git tags (vX.Y.Z format)."""
+    logging.info('Generating switcher.json from git tags (vX.Y.Z)')
     switcher_script = os.path.join(ROOT_DIR, 'scripts', 'generate_switcher.py')
     cmd = [sys.executable, switcher_script]
     if include_current:

scripts/generate_switcher.py

@@ -24,7 +24,7 @@
 
 
 # Must match smv_tag_whitelist in docs/source/conf.py
-SMV_TAG_PATTERN = re.compile(r'^v?\d+\.\d+\.\d+$')
+SMV_TAG_PATTERN = re.compile(r'^v\d+\.\d+\.\d+$')
 
 
 # Paths