Automate generation of switcher.json for Sphinx version dropdown and Introducing incremental documentation builds for dev productivity by sankalps0549 · Pull Request #68 · Autodesk/moldflow-api

sankalps0549 · 2026-03-04T22:09:02Z

Description

This PR introduces the generate_switcher.py script which reads the git tags available to generate the switcher.json file required by the sphinx documentation version switcher. The script validates version.json against the latest git tag on every run, with safeguards to block faulty version progressions (e.g., 27.0.0 → 27.0.2).
Two new flags, --incremental and --include-current, are added to build-docs to speed up local development by skipping already-built tags and allowing the current working tree version to be previewed without creating a git tag.

Fixes # (issue)
#67 - [FEATURE] Automatic generation of switcher.json for sphinx documentation
#69 - [FEATURE] Add --incremental and --include-current flags for faster local docs builds

Type of change

New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation update

Checklist

Please delete options that are not relevant.

I have read the CONTRIBUTING document
My code follows the style guidelines of this project
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes
I have updated the documentation accordingly
I have added a note to CHANGELOG.md describing my changes
My changes generate no new warnings
Any dependent changes have been merged and published

Changes in this PR

Added generate_switcher.py for generating the switcher file required by sphinx documentation version switcher
Updated run.py build-docs command to generate the switcher before generating the documentation pages
Added the --skip-switcher flag to skip the generation of switcher file (for debugging scenarios)
Added --incremental flag to build-docs to only build version tags that don't already have output directories, significantly speeding up repeated local builds
Added --include-current flag to build-docs and generate-switcher to build and include the current working tree version from version.json (when newer than the latest tag) without requiring a git tag
Added generate-switcher command to run.py with --include-current support (for debugging)
Added dirty working tree guard for incremental builds to prevent git checkout failures
Added switcher.json distribution to all version output directories after incremental builds to keep dropdowns in sync
Added version progression validation that always runs (even without --include-current) to catch skipped versions early in CI
Added 55 unit tests for generate_switcher.py covering tag parsing, version sorting, progression rules, and version.json validation

Version Rules

From Version (git tag latest)	To Version (version.json)	Valid?	Rule	Error Message / Notes
27.0.0	27.0.0	⚠️ Same	No change from latest tag	Uses tag as latest, version.json ignored
27.0.0	27.0.1	✅ Pass	Sequential patch increment	Valid progression
27.0.0	27.0.2	❌ FAIL	Cannot skip patch versions	Expected v27.0.1
27.0.0	26.0.5	⚠️ Older	Version older than latest tag	Uses tag v27.0.0 as latest, version.json ignored
27.0.0	26.0.9	⚠️ Older	Version older than latest tag	Uses tag v27.0.0 as latest, version.json ignored
27.0.0	27.1.0	✅ Pass	Valid minor bump with patch reset to 0	Correct progression
27.0.0	27.1.1	❌ FAIL	Patch must be 0 when bumping minor	Expected v27.1.0
27.0.0	27.2.0	❌ FAIL	Cannot skip minor versions	Expected v27.1.0
27.0.0	26.2.3	⚠️ Older	Version older than latest tag	Uses tag v27.0.0 as latest, version.json ignored
27.0.0	26.1.0	⚠️ Older	Version older than latest tag	Uses tag v27.0.0 as latest, version.json ignored
27.0.0	28.0.0	✅ Pass	Valid major bump with minor=0, patch=0	Correct progression
27.0.0	28.0.1	❌ FAIL	Patch must be 0 when bumping major	Expected v28.0.0
27.0.0	28.1.0	❌ FAIL	Minor must be 0 when bumping major	Expected v28.0.0
27.0.0	28.1.1	❌ FAIL	Minor and patch must be 0 when bumping major	Expected v28.0.0
27.0.0	29.0.0	❌ FAIL	Cannot skip major versions	Expected v28.0.0
27.0.0	26.0.3	⚠️ Older	Version older than latest tag	Uses tag v27.0.0 as latest, version.json ignored
27.0.0	24.0.4	⚠️ Older	Version older than latest tag	Uses tag v27.0.0 as latest, version.json ignored

Legend

✅ Pass: Valid version progression, script succeeds, version added to switcher.json
❌ FAIL: Invalid progression, script exits with error code 1, no switcher.json generated
⚠️ Same: version.json matches latest tag, uses tag as latest, version.json NOT added
⚠️ Older: version.json is older than latest tag, uses tag as latest, version.json NOT added

Copilot

Pull request overview

Adds automation to generate the Sphinx version-switcher data (switcher.json) from git tags (and version.json), and wires it into the docs build so the dropdown is no longer maintained manually.

Changes:

Introduces scripts/generate_switcher.py to generate docs/source/_static/switcher.json from git tags (with version progression checks against version.json).
Extends run.py build-docs to generate the switcher before building docs, plus adds run.py generate-switcher and --skip-switcher.
Updates docs/README guidance and CI checkout behavior; removes the committed switcher.json and ignores it going forward.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
scripts/generate_switcher.py	New script to generate switcher.json and validate version progression
run.py	Adds generate-switcher command + integrates switcher generation into build-docs
docs/source/readme.rst	Updates docs instructions to reflect auto-generation and new flag
docs/source/_static/switcher.json	Removes previously committed switcher.json (now generated)
README.md	Updates top-level docs build notes + adds debug command
.gitignore	Ignores generated switcher.json
.github/workflows/ci.yml	Ensures tags are available in CI docs build via `fetch-depth: 0`

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

scripts/generate_switcher.py

run.py

scripts/generate_switcher.py

Copilot

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 9 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

README.md

run.py

scripts/generate_switcher.py

run.py

scripts/generate_switcher.py

run.py

Copilot

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

tests/core/test_generate_switcher.py

scripts/generate_switcher.py

run.py

sankalps0549 · 2026-03-10T20:07:25Z

Hi @osinjoku,
I think we can go ahead and dismiss the security/bandit issues. They appear to be low-severity warnings, mostly triggered by our use of subprocess for running git and other Python commands.

osinjoku · 2026-03-12T03:30:30Z

scripts/generate_switcher.py

+    """Fetch all git tags from the repository."""
+    try:
+        result = subprocess.run(
+            ['git', 'tag', '-l'], cwd=ROOT_DIR, capture_output=True, text=True, check=True


Better to use GitPython?

sankalps0549 added 2 commits March 4, 2026 20:16

Automate generation of switcher.json for Sphinx version dropdown

7510729

Adding check to stop invalid minor and patch updates at once

b303972

sankalps0549 requested a review from Copilot March 4, 2026 22:09

sankalps0549 self-assigned this Mar 4, 2026

sankalps0549 added the enhancement New feature or request label Mar 4, 2026

Copilot started reviewing on behalf of sankalps0549 March 4, 2026 22:09 View session

sankalps0549 linked an issue Mar 4, 2026 that may be closed by this pull request

[FEATURE] Automatic generation of switcher.json for sphinx documentation #67

Open

Copilot AI reviewed Mar 4, 2026

View reviewed changes

sankalps0549 added 2 commits March 10, 2026 08:31

incremental and current builds added for dev env

1e17cca

Version name sanitization

dc38cc2

sankalps0549 requested a review from Copilot March 10, 2026 03:22

Copilot started reviewing on behalf of sankalps0549 March 10, 2026 03:23 View session

Copilot AI reviewed Mar 10, 2026

View reviewed changes

Review comments, and tests addition

d1a7280

sankalps0549 requested a review from Copilot March 10, 2026 19:02

Copilot started reviewing on behalf of sankalps0549 March 10, 2026 19:02 View session

Copilot AI reviewed Mar 10, 2026

View reviewed changes

tests/core/test_generate_switcher.py Outdated Show resolved Hide resolved

scripts/generate_switcher.py Outdated Show resolved Hide resolved

run.py Show resolved Hide resolved

run.py Show resolved Hide resolved

sankalps0549 changed the title ~~Automate generation of switcher.json for Sphinx version dropdown~~ Automate generation of switcher.json for Sphinx version dropdown and Introducing incremental documentation builds for dev productivity Mar 10, 2026

Review comments

2340ee5

sankalps0549 requested review from carri0911, linan-1990, miraladsk, omkar-p-adsk and osinjoku March 10, 2026 20:01

osinjoku reviewed Mar 12, 2026

View reviewed changes

Conversation

sankalps0549 commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Checklist

Changes in this PR

Version Rules

Legend

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sankalps0549 commented Mar 10, 2026

Uh oh!

osinjoku Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sankalps0549 commented Mar 4, 2026 •

edited

Loading