Add various Poly helper methods
#605
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Docs | |
| on: | |
| push: | |
| branches: [develop] | |
| pull_request: | |
| branches: [main, develop] | |
| workflow_call: | |
| workflow_dispatch: | |
| inputs: | |
| tag: | |
| description: The version's tag of the docs to build | |
| required: true | |
| type: string | |
| env: | |
| WORKFLOW_DISPATCH_TAG: ${{ github.event.inputs.tag }} | |
| permissions: | |
| contents: read | |
| jobs: | |
| build: | |
| name: Build | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }} | |
| # NOTE: Fake ternary operator, see https://github.com/actions/runner/issues/409 | |
| fetch-depth: 0 # Fetch all commits and tags, needed for intermediate versions | |
| - name: Set up Python 3.13 | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.13' | |
| cache: 'pip' | |
| cache-dependency-path: | | |
| docs/requirements.txt | |
| pyproject.toml | |
| - name: Upgrade pip | |
| run: python3 -m pip install --upgrade pip | |
| - name: Install the documentation dependencies | |
| run: python3 -m pip install -r docs/requirements.txt | |
| - name: Install the `galois` package | |
| run: python3 -m pip install . | |
| - name: Run Sphinx to build docs | |
| run: sphinx-build -b dirhtml -v docs/ docs/build/ | |
| # Tarring is needed because upload-artifact does not preserve case sensitivity | |
| - name: Tar files | |
| run: tar -czvf docs.tar.gz -C docs/build/ . | |
| - name: Upload artifacts | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: docs | |
| path: docs.tar.gz | |
| retention-days: 30 | |
| publish: | |
| name: Publish | |
| needs: build | |
| # Only publish new docs to GitHub pages if on a pre-release branch or tagged released version | |
| if: ${{ github.event_name == 'push' || github.event_name == 'workflow_call' || github.event_name == 'workflow_dispatch'}} | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: write | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| ref: gh-pages | |
| - name: Download artifacts | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: docs | |
| path: . | |
| - name: Determine folder name | |
| id: folder | |
| shell: python | |
| run: | | |
| import os | |
| import re | |
| github_ref = os.environ.get('GITHUB_REF') | |
| print("github_ref:", github_ref) | |
| github_event_name = os.environ.get("GITHUB_EVENT_NAME") | |
| print("github_event_name:", github_event_name) | |
| workflow_dispatch_tag = os.environ.get("WORKFLOW_DISPATCH_TAG") | |
| print("workflow_dispatch_tag:", workflow_dispatch_tag) | |
| if github_event_name == "push" and github_ref == "refs/heads/develop": | |
| name = "dev" | |
| elif github_event_name == "push" and github_ref.startswith("refs/tags/"): | |
| name = github_ref.split("refs/tags/")[1] | |
| elif github_event_name == "workflow_dispatch": | |
| name = workflow_dispatch_tag | |
| else: | |
| raise RuntimeError | |
| with open(os.environ["GITHUB_OUTPUT"], "a") as f: | |
| f.write(f"name={name}") | |
| - name: Clear old version folder | |
| run: | | |
| rm -rf ${{ steps.folder.outputs.name }} | |
| mkdir ${{ steps.folder.outputs.name }} | |
| # Un-tarring is needed because upload-artifact does not preserve case sensitivity | |
| - name: Untar files | |
| run: tar -xzvf docs.tar.gz -C ${{ steps.folder.outputs.name }} | |
| - name: Remove artifacts | |
| run: rm docs.tar.gz | |
| - name: Update versions.json file | |
| shell: python | |
| run: | | |
| import json | |
| import os | |
| import pathlib | |
| import re | |
| from packaging.version import Version, InvalidVersion | |
| cwd = pathlib.Path.cwd() | |
| # Gather top-level folders (ignore dotfolders) | |
| folders = [p.name for p in cwd.iterdir() if p.is_dir() and not p.name.startswith(".")] | |
| print("folders:", folders) | |
| # Remove "latest" symlink if present (we will recreate it) | |
| if "latest" in folders: | |
| folders.remove("latest") | |
| os.system("rm -f latest") | |
| # Identify release folders like v0.4.9, v1.2.3, v0.5.0rc1, etc. | |
| # Keep it simple: must start with 'v' and be parseable by packaging.version | |
| releases = [] | |
| others = [] | |
| for name in folders: | |
| if name.startswith("v"): | |
| try: | |
| Version(name[1:]) # strip leading 'v' | |
| releases.append(name) | |
| except InvalidVersion: | |
| others.append(name) | |
| else: | |
| others.append(name) | |
| # Sort releases newest -> oldest | |
| releases.sort(key=lambda s: Version(s[1:]), reverse=True) | |
| # Build versions.json entries | |
| list_of_dicts = [] | |
| # Optionally include "dev" first (if present) | |
| if "dev" in others: | |
| list_of_dicts.append({"version": "dev", "title": "dev", "aliases": []}) | |
| latest = None | |
| for v in releases: | |
| aliases = [] | |
| if latest is None: | |
| latest = v | |
| aliases = ["latest"] | |
| os.system(f"ln -s {v} latest") | |
| list_of_dicts.append({"version": v, "title": v, "aliases": aliases}) | |
| print("versions.json:", list_of_dicts) | |
| with (cwd / "versions.json").open("w") as f: | |
| json.dump(list_of_dicts, f, indent=4) | |
| - run: git status | |
| - run: git diff --stat | |
| - uses: stefanzweifel/git-auto-commit-action@v4 | |
| with: | |
| commit_message: Deploy ${{ github.sha }} |