Skip to content

try to get docs version switcher working #1051

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kushalkolar wants to merge 1 commit into
base: main
Choose a base branch
from
Open

try to get docs version switcher working #1051

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 44 additions & 18 deletions .github/workflows/docs-deploy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ jobs:
- uses: actions/checkout@v4
with:
lfs: true
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v5
with:
Expand All @@ -46,28 +47,53 @@ jobs:
- name: Show wgpu backend
run:
python -c "from examples.tests.testutils import wgpu_backend; print(wgpu_backend)"
- name: build docs

# set DOCS_VERSION_DIR (deploy path) and DOCS_VERSION_MATCH (switcher highlight)
# before the build so conf.py and switcher.json generation can use them
- name: Set version environment variables
run: |
cd docs
RTD_BUILD=1 make html SPHINXOPTS="-W --keep-going"
if [ "${{ github.ref_type }}" = "tag" ]; then
TAG="${{ github.ref_name }}"
echo "DOCS_VERSION_DIR=${TAG}" >> "$GITHUB_ENV"
echo "DOCS_VERSION_MATCH=${TAG#v}" >> "$GITHUB_ENV"
elif [ "${{ github.ref }}" = "refs/heads/main" ]; then
echo "DOCS_VERSION_DIR=dev" >> "$GITHUB_ENV"
echo "DOCS_VERSION_MATCH=dev" >> "$GITHUB_ENV"
else
echo "DOCS_VERSION_DIR=${{ github.head_ref }}" >> "$GITHUB_ENV"
echo "DOCS_VERSION_MATCH=dev" >> "$GITHUB_ENV"
fi

# set environment variable `DOCS_VERSION_DIR` to either the pr-branch name, "dev", or the release version tag
- name: set output pr
if: ${{ github.ref != 'refs/heads/main' }}
# sets dir to the branch name when it's a PR
# ex: fastplotlib.org/ver/feature-branch
run: echo "DOCS_VERSION_DIR=$GITHUB_HEAD_REF" >> "$GITHUB_ENV"
- name: Generate switcher.json
run: |
python - <<'EOF'
import json, subprocess, re, pathlib

- name: set output release
if: ${{ github.ref_type == 'tag' }}
# sets dir to the release version tag, ex. v0.3.0 (I think...)
# ex: fastplotlib.org/ver/v0.3.0
run: echo "DOCS_VERSION_DIR=$GITHUB_REF_NAME" >> "$GITHUB_ENV"
tags = subprocess.run(
["git", "tag", "--sort=-version:refname"],
capture_output=True, text=True
).stdout.splitlines()
# exclude pre-v0.3.0 tags (no docs exist for those)
tags = [t for t in tags if re.match(r"^v\d+\.\d+\.\d+$", t) and t >= "v0.3.0"]

- name: set output dev
if: ${{ github.ref == 'refs/heads/main' }}
# any push to main goes to fastplotlib.org/ver/dev
run: echo "DOCS_VERSION_DIR=dev" >> "$GITHUB_ENV"
entries = [{"name": "dev", "version": "dev", "url": "https://www.fastplotlib.org/ver/dev/"}]
for i, tag in enumerate(tags):
ver = tag.lstrip("v")
if i == 0:
entries.append({"name": f"{ver} (stable)", "version": ver,
"url": "https://www.fastplotlib.org/", "preferred": True})
else:
entries.append({"name": ver, "version": ver,
"url": f"https://www.fastplotlib.org/ver/{tag}/"})

p = pathlib.Path("docs/source/_static/switcher.json")
p.write_text(json.dumps(entries, indent=2) + "\n")
EOF

- name: Build docs
run: |
cd docs
DOCS_BUILD=1 make html SPHINXOPTS="-W --keep-going"

# upload docs via SCP
- name: Deploy docs
Expand Down
4 changes: 2 additions & 2 deletions docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,8 +105,8 @@
"show_version_warning_banner": True,
"check_switcher": True,
"switcher": {
"json_url": "http://www.fastplotlib.org/_static/switcher.json",
"version_match": release,
"json_url": "https://www.fastplotlib.org/_static/switcher.json",
"version_match": os.environ.get("DOCS_VERSION_MATCH", release),
},
"icon_links": [
{
Expand Down
Loading