[BUG] Fix: Handle no-tag repositories in build-docs by falling back to current Sphinx build

[sankalps0549]

Description

This PR handles the case when there are no git tags present on the repository. We handle it by falling back to a single build functionality.

Fixes # (issue)
#71 - [BUG] Handle no-tag repositories in build-docs by falling back to current Sphinx build

Type of change

• Bug fix (non-breaking change which fixes an issue)

Checklist

• I have read the CONTRIBUTING document
• My code follows the style guidelines of this project
• New and existing unit tests pass locally with my changes
• I have updated the documentation accordingly
• My changes generate no new warnings
• Any dependent changes have been merged and published

[Copilot]

Pull request overview

This PR addresses Issue #71 by preventing the multi-version docs build path from running in repositories without version tags, and instead falling back to a normal single-version Sphinx build.

Changes:

• Add a _run_sphinx_build() helper to centralize the single-version Sphinx build invocation.
• Detect absence of version tags and fall back from sphinx_multiversion to a single-version Sphinx build.
• Document the fallback behavior in both the Sphinx docs readme and the repository README.

Reviewed changes

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

File	Description
run.py	Adds tag detection + fallback logic and refactors single-version build into _run_sphinx_build().
docs/source/readme.rst	Documents the new “no version tags” fallback behavior for docs builds.
README.md	Adds a note about falling back to single-version docs builds when no v* tags exist.

---

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

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

This PR updates the build-docs command to gracefully handle repositories with no version tags by skipping the multi-version documentation flow and running a normal single-version Sphinx build instead.

Changes:

• Added a helper to run a standard Sphinx single-version build.
• Detected presence/absence of v* tags to decide between multi-version vs single-version docs build.
• Documented the no-tag fallback behavior in the user docs.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
run.py	Adds a no-tag fallback for build-docs and avoids switcher generation when no version tags exist.
docs/source/readme.rst	Documents the fallback to a single-version Sphinx build when no version tags exist.
README.md	Mirrors the same fallback behavior note in the main README.

---

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

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

This PR updates the build-docs workflow to handle repositories without suitable Git version tags by falling back to a standard single-version Sphinx build, and documents that behavior.

Changes:

• Added a dedicated single-version Sphinx build helper and stale switcher.json cleanup.
• Updated build_docs() to detect version tags and choose between multiversion vs single-version build paths.
• Documented the “no version tags” fallback behavior in README.md and docs/source/readme.rst.

Reviewed changes

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

File	Description
run.py	Adds single-version build + stale switcher cleanup, and introduces tag detection/fallback logic in build_docs().
docs/source/readme.rst	Documents fallback behavior when no version tags are present.
README.md	Documents fallback behavior when no version tags are present.

---

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

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

This PR improves the docs build workflow by detecting repositories that have no version tags and falling back to a standard single-version Sphinx build instead of attempting a sphinx-multiversion run that would fail.

Changes:

• Added vX.Y.Z tag detection in run.py and introduced a no-matching-tags fallback to a single-version Sphinx build.
• Tightened the accepted version tag format from v?X.Y.Z to strictly vX.Y.Z across Sphinx config and switcher generation.
• Updated docs and tests to reflect the stricter tag format and new fallback behavior.

Reviewed changes

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

Show a summary per file

File	Description
run.py	Adds tag-regex helper, cleans stale outputs, and implements single-version fallback when no matching version tags exist.
scripts/generate_switcher.py	Aligns tag parsing regex and docstring to require vX.Y.Z.
tests/core/test_generate_switcher.py	Updates expectations to reject non-v tags and reflect new filtering behavior.
docs/source/conf.py	Updates smv_tag_whitelist to require vX.Y.Z.
docs/source/readme.rst	Documents the vX.Y.Z requirement and the no-tag fallback behavior.
README.md	Updates user-facing docs to match the vX.Y.Z requirement and fallback behavior.

---

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

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

This PR fixes run.py build-docs behavior for repositories without matching Git version tags by falling back to a standard single-version Sphinx build instead of attempting a multi-version (sphinx-multiversion) build that can’t succeed.

Changes:

• Require vX.Y.Z-formatted tags consistently across docs config, switcher generation, and tag detection.
• Add a no-matching-tags fallback path in build-docs to run a normal Sphinx build and avoid stale switcher artifacts.
• Update tests and documentation to reflect the stricter tag pattern and new fallback behavior.

Reviewed changes

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

Show a summary per file

File	Description
run.py	Adds vX.Y.Z tag detection helpers and a no-tag fallback to single-version Sphinx builds.
scripts/generate_switcher.py	Tightens tag filtering regex to require vX.Y.Z and updates docstrings accordingly.
tests/core/test_generate_switcher.py	Updates expectations to reject non-v-prefixed tags and adjusts related test cases.
docs/source/conf.py	Aligns smv_tag_whitelist with required vX.Y.Z tag format.
docs/source/readme.rst	Documents vX.Y.Z requirement and the single-version fallback when no matching tags exist.
README.md	Updates user-facing guidance on tag format and fallback behavior.

---

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

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

This PR fixes run.py build-docs failing in repositories with no Git tags by detecting the absence of valid version tags and falling back to a standard single-version Sphinx build, while also aligning the entire docs toolchain on a strict vX.Y.Z tag format.

Changes:

• Require version tags to match vX.Y.Z consistently across Sphinx config, switcher generation, and build logic.
• Add a no-version-tags fallback path in build-docs that removes stale switcher/artifacts and runs a normal Sphinx build.
• Update documentation and tests to reflect the strict tag pattern and the new fallback behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
run.py	Detects whether vX.Y.Z tags exist; falls back to single-version Sphinx build and cleans stale multiversion artifacts/switcher when none exist.
scripts/generate_switcher.py	Tightens tag parsing to require vX.Y.Z tags (matching Sphinx multiversion whitelist).
tests/core/test_generate_switcher.py	Updates tests to assert the stricter v-prefixed tag behavior.
docs/source/conf.py	Aligns smv_tag_whitelist to require vX.Y.Z.
docs/source/readme.rst	Documents the strict tag format and the no-tag fallback behavior for build-docs.
README.md	Documents vX.Y.Z tag requirement and the single-version fallback when tags are absent.

---

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

You can also share your feedback on Copilot code review. Take the survey.