fix: (draft) Fix version dropdown in documentation

.github/workflows/nightly-docs.yml

@@ -53,7 +53,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Deploy development documentation
-        uses: ansys/actions/doc-deploy-dev@v10
+        uses: ansys/actions/doc-deploy-dev@v11.0
         with:
           cname: ${{ env.DOCUMENTATION_CNAME }}
           token: ${{ secrets.GITHUB_TOKEN }}
@@ -66,9 +66,91 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Deploy stable documentation
-        uses: ansys/actions/doc-deploy-stable@v10
+        uses: ansys/actions/doc-deploy-stable@v11.0
         with:
           cname: ${{ env.DOCUMENTATION_CNAME }}
           token: ${{ secrets.GITHUB_TOKEN }}
           bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
-          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}
+          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}
+
+  update_versions_json:
+    name: Update versions.json
+    needs: docs_upload
+    if: needs.docs_upload.result == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate versions.json
+        shell: bash
+        run: |
+          python <<'PY'
+          import json
+          from pathlib import Path
+
+          BASE_URL = "https://visor.docs.pyansys.com"
+          ROOT = Path(".")
+
+          versions = []
+
+          version_root = ROOT / "version"
+
+          if (version_root / "dev").exists():
+              versions.append(
+                  {
+                      "name": "dev",
+                      "version": "dev",
+                      "url": f"{BASE_URL}/version/dev/",
+                  }
+              )
+
+          if (version_root / "stable").exists():
+              versions.append(
+                  {
+                      "name": "stable",
+                      "version": "stable",
+                      "url": f"{BASE_URL}/version/stable/",
+                  }
+              )
+
+          if version_root.exists():
+              numbered = []
+              for child in version_root.iterdir():
+                  if not child.is_dir():
+                      continue
+                  name = child.name
+                  if name in {"dev", "stable"}:
+                      continue
+                  numbered.append(
+                      {
+                          "name": name,
+                          "version": name.removeprefix("v"),
+                          "url": f"{BASE_URL}/version/{name}/",
+                      }
+                  )
+
+              versions.extend(sorted(numbered, key=lambda x: x["name"], reverse=True))
+
+          out = ROOT / "versions.json"
+          out.parent.mkdir(parents=True, exist_ok=True)
+
+          with open(out, "w", encoding="utf-8") as f:
+              json.dump(versions, f, indent=2)
+              f.write("\n")
+          PY
+
+      - name: Show versions.json
+        run: cat versions.json
+
+      - name: Commit and push versions.json
+        shell: bash
+        run: |
+          git config user.name "${{ secrets.PYANSYS_CI_BOT_USERNAME }}"
+          git config user.email "${{ secrets.PYANSYS_CI_BOT_EMAIL }}"
+          git add versions.json
+          git diff --cached --quiet || git commit -m "docs: update version switcher data"
+          git push

doc/changelog.d/41.fixed.md

@@ -0,0 +1 @@
+(draft) Fix version dropdown in documentation

doc/source/conf.py

@@ -1,19 +1,16 @@
 """Sphinx documentation configuration file."""
 
-import base64
 import os
 import runpy
 from datetime import datetime
 
-import requests
 from ansys_sphinx_theme import ansys_favicon, get_version_match
 from sphinx_gallery.sorting import FileNameSortKey
 
 from ansys.visor.viewer import __version__
 
-visor_cname = "visor.docs.pyansys.com"
-
-cname = os.getenv("DOCUMENTATION_CNAME", visor_cname)
+fallback_cname = "visor.docs.pyansys.com"
+cname = os.getenv("DOCUMENTATION_CNAME", fallback_cname)
 """The canonical name of the webpage hosting the documentation."""
 
 # Project information
@@ -67,13 +64,16 @@
     "doc_path": "doc/source",
 }
 
-# specify the location of your github repo
-# Note: if the visor repo becomes public, we can set
-# "json_url": f"https://{cname}/versions.json"
-# and remove fetch_and_save_versions_json()
 html_theme_options = {
     "switcher": {
-        "json_url": "_static/versions.json",
+        # Per the Sphinx documentation:
+        # The JSON file needs to be at a stable, persistent, fully-resolved URL (i.e.,
+        # not specified as a path relative to the sphinx root of the current doc build).
+        # Each version of your documentation should point to the same URL, so that as new
+        # versions are added to the JSON file all the older versions of the docs will gain
+        # switcher dropdown entries linking to the new versions.
+        # from https://pydata-sphinx-theme.readthedocs.io/en/v0.8.1/user_guide/configuring.html?utm_source=openai#configure-switcher-json-url
+        "json_url": f"https://{cname}/versions.json",
         "version_match": switcher_version,
     },
     "github_url": "https://github.com/ansys/visor/",
@@ -189,50 +189,12 @@
 # The master toctree document.
 master_doc = "index"
 
-
 # debugging segfault when running the seupt script
 import faulthandler
 
 faulthandler.enable()
 
 
-def fetch_and_save_versions_json():
-    """
-    Fetches the `versions.json` file from the `gh-pages` branch of the private
-    VISOR repository using the GitHub API and saves it locally to
-    `source/_static/versions.json`.
-
-    This is required for the version switcher, as the repository is private and
-    the file cannot be accessed via the GitHub Pages URL without authentication.
-
-    Requires a valid `GITHUB_TOKEN` for authentication.
-    This is automatically set in the GitHub Actions workflow, but must be set
-    manually for local builds, e.g.:
-        export GITHUB_TOKEN="your_tokem_here"
-    """
-    owner = "ansys"
-    repo = "visor"
-    branch = "gh-pages"
-    file_path = "versions.json"
-    api_url = f"https://api.github.com/repos/{owner}/{repo}/contents/{file_path}?ref={branch}"
-    token = os.getenv("GITHUB_TOKEN")
-    headers = {"Authorization": f"Bearer {token}"} if token else {}
-
-    local_path = os.path.join("source", "_static", "versions.json")
-    print(f"Fetching {file_path} from {repo}@{branch} via GitHub API...")
-
-    try:
-        response = requests.get(api_url, headers=headers)
-        response.raise_for_status()
-        content = response.json()["content"]
-        decoded = base64.b64decode(content).decode("utf-8")
-        with open(local_path, "w+", encoding="utf-8") as f:
-            f.write(decoded)
-        print(f"Saved versions.json to {local_path}")
-    except Exception as e:
-        print(f"Error fetching versions.json: {e}")
-
-
 # Run the script to generate an updated OpenAPI JSON file
 
 def generate_openapi_json():
@@ -243,7 +205,6 @@ def generate_openapi_json():
 
 def setup(app):
     app.connect('builder-inited', lambda app: generate_openapi_json())
-    app.connect('builder-inited', lambda app: fetch_and_save_versions_json())
     app.add_css_file("css/reset.css")
 
 linkcheck_ignore = []

pyproject.toml

@@ -9,7 +9,7 @@ build-system-version = "1.7.0"
 
 [tool.poetry]
 name = "ansys-visor-viewer"
-version = "1.0.0_beta"
+version = "1.0.0_beta_dev"
 description = "\"VISOR 3D visualization web component framework\""
 authors = ["VISOR Team <visor@ansys.com>"]
 readme = "README.rst"