Repository navigation
Enable version switcher in Python documentation - #92
Vamsi-2581 wants to merge 17 commits into
Conversation
|
Sorry, I am not sure how this works. How is the json file created? How is it updated? |
|
I checked the configured URL: |
This PR needs to figure out how versions.json is generated and updated when a new release is made. |
|
Hi @MLopez-Ibanez, thanks for checking! Here is how
If you're happy with the |
|
OK, do that. |
Updated deployment logic for documentation and added version handling.
|
It seems the yml file is not valid according to pre-commit. Moving the embedded python to a helper script as suggested in my comment will probably fix the issue (or make it easier to spot). |
…ns.py This script loads existing versions from a JSON file in a Git repository, updates the version list with a new version entry, and saves the updated list to a local JSON file.
Add docstring for version update script
Added docstrings to functions for better documentation.
There was a problem hiding this comment.
🟡 Changes recommended
A Bash syntax error blocks all main-branch and release deployments, while the publishing changes leave the documentation root stale and risk discarding existing version entries after a failed fetch.
3 open issues
What changed in this PR
Adds a PyData Sphinx Theme version switcher to the Python documentation, addressing #91, with metadata maintained by the documentation deployment workflow.
Changes:
- Enables the dropdown with version matching for releases, development builds, and pull request previews.
- Adds a script to maintain
versions.jsonand mark the latest published release as preferred. - Updates deployment paths to separate development and release documentation and publish shared version metadata.
| File | Description |
|---|---|
python/doc/update_versions.py |
Generates version-switcher metadata while preserving existing entries. |
python/doc/source/conf.py |
Enables and configures the documentation version dropdown. |
.github/workflows/python.yml |
Adds versioned deployment paths and metadata publication. |
Review effort: Balanced
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
MLopez-Ibanez
left a comment
There was a problem hiding this comment.
In addition to the inline comments, we should follow numpy and create/update a symlink that points to the stable version, then add notices for versions that are not the stable one:
https://github.com/numpy/doc/blob/main/_static/versions.json
I am a bit hesitant to merge this without seeing a deployment. Could you run this in your fork and post a link to the generated docs so we can see how the generated versions.json file and the HMTL documentation look like.
| env: | ||
| DEST: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || 'main' }} | ||
| run: | | ||
| if [ "${{ github.event_name }}" = "pull_request" ]; then DEST="pr-${{ github.event.pull_request.number }}"; elif [ "${{ github.event_name }}" = "release" ]; then DEST="${GITHUB_REF_NAME#v}"; else DEST="dev"; fi |
There was a problem hiding this comment.
Instead of the bash conditional you can use:
env:
DEST: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || github.event_name == 'release' && github.ref_name || 'dev' }}
run: |
DEST="${DEST#v}"
| - name: Prepare versions.json | ||
| id: ver | ||
| run: | | ||
| if [ "${{ github.event_name }}" = "release" ]; then VERSION="${GITHUB_REF_NAME#v}"; else VERSION="dev"; fi |
There was a problem hiding this comment.
Instead of the bash conditional, you can use:
env:
VERSION: ${{ github.event_name == 'release' && github.ref_name || 'dev' }}
run: |
VERSION="${VERSION#v}"
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
python3 python/doc/update_versions.py "$VERSION"
Also update_versions.py should do the git fetch and exit with an error if it fails.
| else: | ||
| switcher_version = version | ||
|
|
||
| switcher_json_url = f"{html_site_root}versions.json" |
There was a problem hiding this comment.
Have you tested that this works when you build the documentation locally in your computer? The github action does not place version.json at the root of the documentation but one folder above it.
There was a problem hiding this comment.
html_site_root points to .../moocore/python/ (one level above the versioned doc folders), so switcher_json_url resolves to .../moocore/python/versions.json. Local builds still succeed because PyData Sphinx Theme fetches that URL in the browser, though the dropdown stays empty until versions.json is published.
| @@ -0,0 +1,62 @@ | |||
| """Update versions.json for PyData Sphinx Theme version switcher.""" | |||
There was a problem hiding this comment.
It would be better to pass the version as a mandatory argument rather than reading the environment variables.
The script should also do git fetch. An updated version could be
""Update versions.json for PyData Sphinx Theme version switcher."""
import argparse
import json
import subprocess
from pathlib import Path
BASE = "https" + "://multi-objective.github.io/moocore/python/"
def load_existing_versions() -> list[dict]:
"""Load existing version entries from gh-pages."""
subprocess.run(["git", "fetch", "origin", "gh-pages"], check=True)
result = subprocess.run(
["git", "show", "origin/gh-pages:python/versions.json"],
capture_output=True,
text=True,
check=False,
)
if result.returncode != 0 or not result.stdout.strip():
return []
data = json.loads(result.stdout)
return data if isinstance(data, list) else []
def update_versions(version: str) -> None:
"""Update versions.json with the given documentation version."""
data = load_existing_versions()
if version == "dev":
entry = {"name": "dev", "version": "dev", "url": BASE + "dev/"}
else:
entry = {
"version": version,
"url": f"{BASE}{version}/",
"preferred": True,
}
for item in data:
if isinstance(item, dict):
item.pop("preferred", None)
updated = [
item
for item in data
if not (isinstance(item, dict) and item.get("version") == version)
]
updated.append(entry)
out_dir = Path("versions_meta")
out_dir.mkdir(parents=True, exist_ok=True)
with (out_dir / "versions.json").open("w", encoding="utf-8") as f:
json.dump(updated, f, indent=2)
f.write("\n")
def main() -> None:
"""Parse the target version and update versions.json."""
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("version", help="documentation version to publish")
args = parser.parse_args()
update_versions(args.version)
if __name__ == "__main__":
main()| import sys | ||
| from pathlib import Path | ||
|
|
||
| BASE = "https" + "://multi-objective.github.io/moocore/python/" |
There was a problem hiding this comment.
This url should be taken from html_site_root in conf.py There must be a way to share common data via a site.json or some similar configuration file.
Refactor update_versions.py to improve version handling and add argument parsing.
for more information, see https://pre-commit.ci
for more information, see https://pre-commit.ci
Refactor environment variable assignments for DEST and VERSION in the GitHub Actions workflow.
|
I've updated the workflow to use |


Closes #91
Enable the PyData Sphinx Theme version switcher in the Python documentation. The switcher reads the published
versions.json, matchesdevfor development builds, and matches the PR head ref in GitHub Actions previews so preview pages are not mistaken for released versions.The existing Python documentation workflow builds docs for pull requests, providing validation for this change.