Skip to content

Enable version switcher in Python documentation - #92

Open
Vamsi-2581 wants to merge 17 commits into
multi-objective:mainfrom
Vamsi-2581:codex/python-doc-version-switcher
Open

Vamsi-2581 wants to merge 17 commits into
multi-objective:mainfrom
Vamsi-2581:codex/python-doc-version-switcher

Conversation

@Vamsi-2581

Copy link
Copy Markdown

Closes #91

Enable the PyData Sphinx Theme version switcher in the Python documentation. The switcher reads the published versions.json, matches dev for 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.

@MLopez-Ibanez

Copy link
Copy Markdown
Contributor

Sorry, I am not sure how this works. How is the json file created? How is it updated?

@MLopez-Ibanez
MLopez-Ibanez marked this pull request as draft November 3, 2026 07:54
@Vamsi-2581

Copy link
Copy Markdown
Author

I checked the configured URL: https://multi-objective.github.io/moocore/python/versions.json currently returns 404. The python.yml workflow deploys artifact/main to the gh-pages branch under python/ with clean: true, and I found no workflow step that generates a versions manifest. The PyData Sphinx Theme expects a persistent JSON list shared by all documentation versions. Does the project intend that manifest to be added to this repo and updated as part of releases, or is it maintained elsewhere? I’ve left this PR as a draft until the manifest source and update path are clear.

@MLopez-Ibanez

Copy link
Copy Markdown
Contributor

I checked the configured URL: https://multi-objective.github.io/moocore/python/versions.json currently returns 404. The python.yml workflow deploys artifact/main to the gh-pages branch under python/ with clean: true, and I found no workflow step that generates a versions manifest. The PyData Sphinx Theme expects a persistent JSON list shared by all documentation versions. Does the project intend that manifest to be added to this repo and updated as part of releases, or is it maintained elsewhere? I’ve left this PR as a draft until the manifest source and update path are clear.

This PR needs to figure out how versions.json is generated and updated when a new release is made.

@Vamsi-2581

Copy link
Copy Markdown
Author

Hi @MLopez-Ibanez, thanks for checking! Here is how pydata-sphinx-theme's version switcher works and what we'd need in .github/workflows/python.yml:

  1. How versions.json is structured: conf.py points the switcher at versions.json under python/ (e.g. a JSON array of { "name", "version", "url", "preferred" } entries for dev and each released version).
  2. Why it isn't generated yet: Currently deploy-docs in .github/workflows/python.yml deploys main into a flat gh-pages/python/ directory with clean: true, so there are no versioned subfolders (python/dev/, python/<version>/) or versions.json on gh-pages yet.
  3. How we can automate it in python.yml:
    • Deploy main builds to target-folder: python/dev (with clean: true only inside python/dev).
    • On release: published, deploy to target-folder: python/<version> (and optionally python/stable).
    • Have a small Python step in deploy-docs read/update python/versions.json on gh-pages (adding the new release entry, marking it "preferred": true, and keeping dev + existing versions).

If you're happy with the python/dev/ + python/<version>/ layout on gh-pages, I can add the versions.json generation/update step to .github/workflows/python.yml in this PR!

@MLopez-Ibanez

Copy link
Copy Markdown
Contributor

OK, do that.

@Vamsi-2581
Vamsi-2581 marked this pull request as ready for review November 16, 2026 16:15
Comment thread .github/workflows/python.yml Resolved
@MLopez-Ibanez

Copy link
Copy Markdown
Contributor

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.
Comment thread .github/workflows/python.yml Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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.json and 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

Comment thread .github/workflows/python.yml Resolved
Comment thread .github/workflows/python.yml Resolved
Comment thread .github/workflows/python.yml Resolved
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

@MLopez-Ibanez MLopez-Ibanez left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

numpy/doc#7

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.

Comment thread .github/workflows/python.yml Outdated
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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}"

Comment thread .github/workflows/python.yml Outdated
- name: Prepare versions.json
id: ver
run: |
if [ "${{ github.event_name }}" = "release" ]; then VERSION="${GITHUB_REF_NAME#v}"; else VERSION="dev"; fi

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread python/doc/source/conf.py
else:
switcher_version = version

switcher_json_url = f"{html_site_root}versions.json"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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."""

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 environment variable assignments for DEST and VERSION in the GitHub Actions workflow.
@Vamsi-2581

Copy link
Copy Markdown
Author

I've updated the workflow to use env expressions, moved BASE into a shared python/doc/site.json read by both conf.py and update_versions.py, made version a required CLI argument with git fetch ... check=True, added a stable symlink on release deployments, and enabled show_version_warning_banner: True in conf.py.
I'll run the workflow on my fork next and post the preview link here.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add version switcher dropdown to Python documentation

3 participants