Sphinx Versioning (#61)

sankalps0549 · Copilot · web-flow · commit 844d1485a9bd · 2026-01-19T13:19:50.000+05:30
* Sphinx Versioning * Linking latest dir rather than copying * Function signaturevariable name fixed * source validaton for latest * Try catch for git tags absence Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Lint and format issue solve * lint fix * Indentation fix Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Updating publish workflow (#59) * Introduce Sphinx Versioning (#57) * Sphinx Versioning * Linking latest dir rather than copying * Function signaturevariable name fixed * source validaton for latest * Try catch for git tags absence Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Lint and format issue solve * lint fix * Indentation fix Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Lint fix * fetch tags in ci * Readme fix * Remove force --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Support local builds for a single version and redirect root to latest (#60) * Introduce Sphinx Versioning (#57) * Sphinx Versioning * Linking latest dir rather than copying * Function signaturevariable name fixed * source validaton for latest * Try catch for git tags absence Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Lint and format issue solve * lint fix * Indentation fix Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Lint fix * fetch tags in ci * Readme fix * Remove force * Local build single version * Redirect the root to latest * Documentation update * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -76,6 +76,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # Fetch all history for sphinx-multiversion
 
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -143,6 +145,9 @@ jobs:
       - name: Configure Pages
         uses: actions/configure-pages@v5
 
+      - name: Fetch Git tags
+        run: git fetch --tags
+
       - name: Build documentation
         run: python run.py build-docs
 
diff --git a/README.md b/README.md
@@ -68,13 +68,25 @@ python run.py build
 python run.py build-docs
 ```
 
-> ***Note:  When releasing a new version, update ``switcher.json`` in ``docs/source/_static/`` 
-   to include the new tag in the version dropdown for documentation.***
+> ***Note:  When releasing a new version, update ``switcher.json`` in ``docs/source/_static/`` to include the new tag in the version dropdown for documentation.***
 
 Options:
 - `--skip-build` (`-s`): Skip building before generating docs
+- `--local` (`-l`): Build documentation locally for a single version (skips multi-version build)
 
-The documentation can be accessed locally by opening the index.html in the docs/build/html/ folder.
+The documentation can be accessed locally by serving the docs/build/html/ folder:
+```sh
+cd docs/build/html
+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/`)
+- 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
 
 ### Running the Formatter
 
diff --git a/docs/source/readme.rst b/docs/source/readme.rst
@@ -1258,10 +1258,31 @@ The project includes a ``run.py`` script with several useful commands:
 - ``python run.py build-docs`` - Build versioned documentation (HTML uses git tags for the
   navigation dropdown; run ``git fetch --tags`` locally before building)
 
+  - ``--skip-build`` (``-s``): Skip building the package before generating docs
+  - ``--local`` (``-l``): Build documentation locally for a single version (skips multi-version build)
+
 .. note::
    When releasing a new version, update ``switcher.json`` in ``docs/source/_static/`` 
    to include the new tag in the version dropdown.
 
+**Viewing Documentation Locally**
+
+After building, serve the documentation using Python's built-in HTTP server:
+
+.. code-block:: bash
+
+   cd docs/build/html
+   python -m http.server 8000
+
+Then open http://localhost:8000 in your browser.
+
+**Versioned Documentation Features:**
+
+- Each git tag 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
+
 Contributing
 ============
 
diff --git a/run.py b/run.py
@@ -7,7 +7,7 @@
 Usage:
     run.py clean-up
     run.py build [-P | --publish] [-i | --install]
-    run.py build-docs [-t <target> | --target=<target>] [-s | --skip-build]
+    run.py build-docs [-t <target> | --target=<target>] [-s | --skip-build] [-l | --local]
     run.py format [--check]
     run.py install [-s | --skip-build]
     run.py install-package-requirements
@@ -51,6 +51,7 @@
     --all                           Run all tests.
     --repo-url=<url>                Custom PyPI repository URL.
     --github-api-url=<url>          Custom GitHub API URL.
+    -l, --local                     Build documentation locally (single version).
 """
 
 import os
@@ -328,6 +329,31 @@ def build_mo():
         )
 
 
+def create_root_redirect(build_output: str) -> None:
+    """Create an index.html in the versioned HTML build output root that redirects to /latest/."""
+    index_path = os.path.join(build_output, 'index.html')
+    redirect_html = """<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>Redirecting to latest documentation...</title>
+    <meta http-equiv="refresh" content="0; url=./latest/">
+    <link rel="canonical" href="./latest/">
+    <script>window.location.replace("./latest/");</script>
+</head>
+<body>
+    <p>Redirecting to <a href="./latest/">latest documentation</a>...</p>
+</body>
+</html>
+"""
+    try:
+        with open(index_path, 'w', encoding='utf-8') as f:
+            f.write(redirect_html)
+        logging.info("Created root redirect: index.html -> latest/")
+    except Exception as err:
+        logging.warning("Could not create root redirect index.html: %s", err)
+
+
 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')]
@@ -373,7 +399,7 @@ def version_key(v):
         shutil.copytree(latest_src, latest_dest)
 
 
-def build_docs(target, skip_build):
+def build_docs(target, skip_build, local=False):
     """Build Documentation"""
 
     if not skip_build:
@@ -386,7 +412,7 @@ def build_docs(target, skip_build):
         shutil.rmtree(DOCS_BUILD_DIR)
 
     try:
-        if target == 'html':
+        if target == 'html' and not local:
             build_output = os.path.join(DOCS_BUILD_DIR, 'html')
             try:
                 # fmt: off
@@ -409,6 +435,7 @@ def build_docs(target, skip_build):
                 raise
             # fmt: on
             create_latest_alias(build_output)
+            create_root_redirect(build_output)
         else:
             # For other targets such as latex, pdf, etc.
             run_command(
@@ -737,8 +764,9 @@ def main():
         elif args.get('build-docs'):
             target = args.get('--target') or args.get('-t') or 'html'
             skip_build = args.get('--skip-build') or args.get('-s')
+            local = args.get('--local') or args.get('-l')
 
-            build_docs(target=target, skip_build=skip_build)
+            build_docs(target=target, skip_build=skip_build, local=local)
 
         elif args.get('install-package-requirements'):
             install_package(target_path=os.path.join(ROOT_DIR, SITE_PACKAGES))
