Skip to content

[FEATURE] Add --incremental and --include-current flags for faster local docs builds #69

@sankalps0549

Description

@sankalps0549

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-current

Additional context

  • In production/CI, the default full build is used — --incremental and --include-current are development conveniences only.
  • --incremental requires a clean working tree (enforced via git status --porcelain) since it checks out tags in-place.
  • version.json is always validated against the latest git tag to catch version progression errors (e.g. skipping v27.0.1 by jumping from v27.0.0 to v27.0.3) regardless of whether --include-current is set. The flag only controls whether the version appears in the built output.
  • After an incremental build, the generated switcher.json is distributed to all version output directories so every version's dropdown stays in sync.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions