-
Notifications
You must be signed in to change notification settings - Fork 1
Closed
Closed
Copy link
Labels
enhancementNew feature or requestNew feature or request
Description
Is your feature request related to a problem? Please describe.
Building documentation with sphinx-multiversion rebuilds every tagged version from scratch on each run. For a repository with many version tags, this is slow and wasteful during local development. Additionally, there is no way to preview documentation for the current working tree (e.g. an in-progress release) in the multi-version docs output — you must create a git tag first, which is not practical during development.
Describe the solution you'd like
Two new flags for run.py build-docs:
--incremental— Only build documentation for version tags that don't already have an output directory. Previously built versions are preserved, significantly speeding up repeated local builds.--include-current— Read version.json and, if it contains a version newer than the latest git tag, build documentation for the current working tree and include it in the version switcher dropdown. This allows previewing unreleased documentation without creating a tag.
API Design (if applicable)
# Full rebuild (existing behavior, unchanged)
python run.py build-docs
# Incremental: only build tags that are missing from the output
python run.py build-docs --incremental
# Incremental + include current working tree version
python run.py build-docs --incremental --include-current
# Also available on the standalone switcher command
python run.py generate-switcher --include-currentAdditional context
- In production/CI, the default full build is used —
--incrementaland--include-currentare development conveniences only. --incrementalrequires a clean working tree (enforced viagit status --porcelain) since it checks out tags in-place.version.jsonis always validated against the latest git tag to catch version progression errors (e.g. skippingv27.0.1by jumping fromv27.0.0tov27.0.3) regardless of whether--include-currentis set. The flag only controls whether the version appears in the built output.- After an incremental build, the generated
switcher.jsonis distributed to all version output directories so every version's dropdown stays in sync.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request