Automate generation of switcher.json for Sphinx version dropdown and Introducing incremental documentation builds for dev productivity

.github/workflows/ci.yml

@@ -51,6 +51,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # Fetch all history and tags
 
       - name: Set up Python
         uses: actions/setup-python@v5

.gitignore

@@ -71,6 +71,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/_static/switcher.json
 
 # PyBuilder
 .pybuilder/

README.md

@@ -68,11 +68,46 @@ 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.***
+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.
 
 Options:
 - `--skip-build` (`-s`): Skip building before generating docs
 - `--local` (`-l`): Build documentation locally for a single version (skips multi-version build)
+- `--skip-switcher`: Skip generating switcher.json (useful for offline builds or custom switcher configurations)
+- `--include-current`: Include current working tree version from version.json in switcher (useful during development before tagging)
+- `--incremental`: Only build versions that don't have existing output directories (speeds up development by skipping already-built versions)
+
+**Debug command:** To manually generate `switcher.json` without building docs:
+```sh
+python run.py generate-switcher
+```
+
+**Development workflow:** When working on a version bump before tagging:
+```sh
+# Build docs including your current unreleased version
+# This will:
+#  1. Build all tagged versions via sphinx_multiversion
+#  2. Build current working tree version via sphinx
+#  3. Add current version to switcher.json as latest
+python run.py build-docs --include-current
+```
+
+**Note:** By default, if `version.json` contains a version newer than the latest git tag, it will be validated but NOT added to the switcher (to prevent broken links). Use `--include-current` to build and include it during development, or create a git tag to include it permanently.
+
+**Fast development iteration:**
+```sh
+# First build (builds all versions)
+python run.py build-docs --include-current
+
+# Subsequent builds (only rebuilds current version, skips existing tagged versions)
+python run.py build-docs --include-current --incremental
+```
+
+**How `--incremental` works:**
+- Checks which version directories already exist in `docs/build/html/`
+- For missing tagged versions: checks out each tag, builds docs, then restores your branch
+- For current version (with `--include-current`): only builds if directory doesn't exist
+- Useful during development to avoid rebuilding all historical versions every time
 
 The documentation can be accessed locally by serving the docs/build/html/ folder:
 ```sh

docs/source/readme.rst

@@ -1259,10 +1259,29 @@ The project includes a ``run.py`` script with several useful commands:
 
   - ``--skip-build`` (``-s``): Skip building the package before generating docs
   - ``--local`` (``-l``): Build documentation locally for a single version (skips multi-version build)
+  - ``--skip-switcher``: Skip generating switcher.json (useful for offline builds or custom switcher configurations)
+  - ``--include-current``: Build and include current working tree version from version.json (useful during development before tagging)
+  - ``--incremental``: Only build versions that don't have existing output directories (speeds up development by skipping already-built versions)
 
 .. note::
-   When releasing a new version, update ``switcher.json`` in ``docs/source/_static/`` 
-   to include the new tag in the version dropdown.
+   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.
+
+**Incremental Builds for Development:**
+
+For faster iteration during development, combine ``--include-current`` with ``--incremental``:
+
+.. code-block:: bash
+
+   # First build (builds all versions)
+   python run.py build-docs --include-current
+
+   # Subsequent builds (only rebuilds current version)
+   python run.py build-docs --include-current --incremental
+
+The ``--incremental`` flag preserves existing version builds and only builds what's missing, significantly speeding up documentation updates during development.
 
 **Viewing Documentation Locally**
 

pyproject.toml

@@ -1,3 +1,6 @@
 [build-system]
 requires = ["setuptools>=75.0"]
 build-backend = "setuptools.build_meta"
+
+[tool.pyright]
+extraPaths = ["scripts"]

pytest.ini

@@ -3,6 +3,8 @@ markers =
     unit: Unit tests that run quickly and test small pieces of functionality
     integration: Integration tests that check multiple components together
     core: Core functionality tests
+    scripts: Scripts tests
+    generate_switcher: Tests for scripts/generate_switcher.py
     file_set(set_name): Mark test to run on a specific FileSet
     json_file_name(file_name): Mark test to use a specific JSON file for expected data
     cad_manager: Tests the CADManager class

requirements.txt

@@ -2,6 +2,7 @@ black==25.1.0
 build==1.2.2.post1
 coverage==7.6.12
 docopt==0.6.2
+gitpython==3.1.46
 packaging==24.2
 pathspec==0.12.1
 polib==1.2.0