Adding version switcher to CI

.github/pages/switcher.py

@@ -0,0 +1,41 @@
+"""Create/modify switcher.json to allow docs to switch between different versions."""
+
+import json, os
+from argparse import ArgumentParser
+from pathlib import Path
+
+
+def get_versions(root: str) -> list[str]:
+    """Generate a list of versions."""
+    versions = sorted([ f.name for f in os.scandir(root) if f.is_dir() ])
+    print(f"Sorted versions: {versions}")
+    return versions
+
+
+def write_json(path: Path, repository: str, versions: list[str]):
+    """Write the JSON switcher to path."""
+    org, repo_name = repository.split("/")
+    struct = [
+        {"version": version, "url": f"https://{org}.github.io/{repo_name}/{version}/"}
+        for version in versions
+    ]
+    text = json.dumps(struct, indent=2)
+    print(f"JSON switcher:\n{text}")
+    path.write_text(text, encoding="utf-8")
+
+
+def main(args=None):
+    """Parse args and write switcher."""
+    parser = ArgumentParser(description="Make a versions.json file")
+    parser.add_argument("root", type=Path, help="Path to root directory with all versions of docs")
+    parser.add_argument("repository", help="The GitHub org and repository name: ORG/REPO")
+    parser.add_argument("output", type=Path, help="Path of write switcher.json to")
+    args = parser.parse_args(args)
+
+    # Write the versions file
+    versions = get_versions(args.root)
+    write_json(args.output, args.repository, versions)
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/_build_docs.yaml

@@ -50,9 +50,3 @@ jobs:
         with:
           name: docs-${{ inputs.tag }}
           path: artifacts
-
-      - name: Upload index.html as Artifact
-        uses: actions/[email protected]
-        with:
-          name: docs-index-html
-          path: docs/index.html

.github/workflows/_github_pages.yaml

@@ -14,7 +14,7 @@ jobs:
       - name: Setup Pages
         uses: actions/[email protected]
 
-      - name: Download Latest Docs Artifact
+      - name: Download All Docs Artifact
         uses: actions/[email protected]
         with:
           pattern: docs-*

.github/workflows/_switcher.yaml

@@ -0,0 +1,32 @@
+on:
+  workflow_call:
+
+jobs:
+  version_switcher:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PtyPy Code
+        uses: actions/checkout@v4
+
+      - name: Upload index.html as Artifact
+        uses: actions/[email protected]
+        with:
+          name: docs-index-html
+          path: .github/pages/index.html
+
+      - name: Download All Docs Artifact
+        uses: actions/[email protected]
+        with:
+          pattern: docs-*
+          merge-multiple: true
+          path: ./doc_versions
+
+      - name: Create Switcher File
+        run: python .github/pages/switcher.py ./doc_versions ${{ github.repository }} .github/pages/switcher.json
+
+      - name: Upload switcher.json as Artifact
+        uses: actions/[email protected]
+        with:
+          name: docs-switcher-json
+          path: .github/pages/switcher.json
+

.github/workflows/docs.yaml

@@ -5,6 +5,8 @@ on:
     branches:
       - master
       - dev
+  release:
+    type: [published]
 
 jobs:
   legacy_docs:
@@ -17,8 +19,12 @@ jobs:
     with:
       tag: ${{ github.ref_name }}
 
-  github_pages:
+  switcher:
+    uses: ./.github/workflows/_switcher.yaml
     needs:
       - legacy_docs
       - new_docs
+
+  github_pages:
+    needs: switcher
     uses: ./.github/workflows/_github_pages.yaml