From 9c979497f6558d8441052816b1d14e7d57fc12ed Mon Sep 17 00:00:00 2001 From: ansbbrooks Date: Wed, 26 Aug 2026 22:19:39 -0500 Subject: [PATCH 1/6] Fix doc version dropdown --- .github/workflows/nightly-docs.yml | 95 +++++++++++++++++++++++++++--- .gitignore | 3 +- doc/changelog.d/41.fixed.md | 1 + doc/source/conf.py | 61 ++++--------------- 4 files changed, 103 insertions(+), 57 deletions(-) create mode 100644 doc/changelog.d/41.fixed.md diff --git a/.github/workflows/nightly-docs.yml b/.github/workflows/nightly-docs.yml index a51b815c..6e9d0756 100644 --- a/.github/workflows/nightly-docs.yml +++ b/.github/workflows/nightly-docs.yml @@ -9,8 +9,7 @@ on: tags: [ 'v*' ] env: - # Uncomment the following line to enable custom CNAME for documentation - # DOCUMENTATION_CNAME: 'visor.staging.local' + DOCUMENTATION_CNAME: 'supreme-fiesta-v6v17mm.pages.github.io' MAIN_PYTHON_VERSION: '3.11' GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} @@ -54,10 +53,9 @@ 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: - # Uncomment the following line to enable custom CNAME for documentation - # cname: ${{ env.DOCUMENTATION_CNAME }} + cname: ${{ env.DOCUMENTATION_CNAME }} token: ${{ secrets.GITHUB_TOKEN }} bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }} bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }} @@ -68,8 +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 }} \ No newline at end of file + 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://supreme-fiesta-v6v17mm.pages.github.io" + 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 \ No newline at end of file diff --git a/.gitignore b/.gitignore index f51b0295..9aea8c50 100644 --- a/.gitignore +++ b/.gitignore @@ -211,5 +211,4 @@ doc/source/_autosummary doc/source/_static/versions.json doc/source/examples doc/source/http_api_reference/openapi.json -doc/source/sg_execution_times.rst - +doc/source/sg_execution_times.rst \ No newline at end of file diff --git a/doc/changelog.d/41.fixed.md b/doc/changelog.d/41.fixed.md new file mode 100644 index 00000000..b9052c19 --- /dev/null +++ b/doc/changelog.d/41.fixed.md @@ -0,0 +1 @@ +Fix version dropdown in documentation diff --git a/doc/source/conf.py b/doc/source/conf.py index 7be3e345..03645ffc 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,21 +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__ -# TODO: Set up namespace for VISOR docs and update here -# visor_cname = "visor.docs.solutions.ansys.com" -visor_cname = "vigilant-lamp-162kw9z.pages.github.io" - -cname = os.getenv("DOCUMENTATION_CNAME", visor_cname) +fallback_cname = "supreme-fiesta-v6v17mm.pages.github.io" +cname = os.getenv("DOCUMENTATION_CNAME", fallback_cname) """The canonical name of the webpage hosting the documentation.""" # Project information @@ -75,7 +70,14 @@ # 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/", @@ -191,50 +193,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,11 +207,12 @@ def generate_openapi_json(): except Exception as e: print(f"Error running generate_openapi.py: {e}") + 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 = [] # If we are on a release, we have to ignore the "release" URLs, since it is not @@ -255,4 +220,4 @@ def setup(app): if switcher_version != "dev": linkcheck_ignore.append( f"https://github.com/ansys/visor/releases/tag/v{__version__}" - ) \ No newline at end of file + ) From 864f29fe100821a23a683d0399bdc03712806c53 Mon Sep 17 00:00:00 2001 From: ansbbrooks Date: Wed, 26 Aug 2026 22:21:03 -0500 Subject: [PATCH 2/6] revert .gitignore changes --- .gitignore | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 9aea8c50..f51b0295 100644 --- a/.gitignore +++ b/.gitignore @@ -211,4 +211,5 @@ doc/source/_autosummary doc/source/_static/versions.json doc/source/examples doc/source/http_api_reference/openapi.json -doc/source/sg_execution_times.rst \ No newline at end of file +doc/source/sg_execution_times.rst + From c5e717c0baf6f159fe9c36569c3ff9adb5932215 Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Thu, 27 Aug 2026 03:23:50 +0000 Subject: [PATCH 3/6] chore: adding changelog file 41.fixed.md [dependabot-skip] --- doc/changelog.d/41.fixed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/changelog.d/41.fixed.md b/doc/changelog.d/41.fixed.md index b9052c19..acd25825 100644 --- a/doc/changelog.d/41.fixed.md +++ b/doc/changelog.d/41.fixed.md @@ -1 +1 @@ -Fix version dropdown in documentation +(draft) Fix version dropdown in documentation From bce4c5820051e1d1a304d41880b96c353124fdea Mon Sep 17 00:00:00 2001 From: ansbbrooks Date: Thu, 27 Aug 2026 10:33:13 -0500 Subject: [PATCH 4/6] use "visor.docs.pyansys.com" for cname --- .github/workflows/nightly-docs.yml | 4 ++-- doc/source/conf.py | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/nightly-docs.yml b/.github/workflows/nightly-docs.yml index 6e9d0756..20a54403 100644 --- a/.github/workflows/nightly-docs.yml +++ b/.github/workflows/nightly-docs.yml @@ -9,7 +9,7 @@ on: tags: [ 'v*' ] env: - DOCUMENTATION_CNAME: 'supreme-fiesta-v6v17mm.pages.github.io' + DOCUMENTATION_CNAME: 'visor.docs.pyansys.com' MAIN_PYTHON_VERSION: '3.11' GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} @@ -92,7 +92,7 @@ jobs: import json from pathlib import Path - BASE_URL = "https://supreme-fiesta-v6v17mm.pages.github.io" + BASE_URL = "https://visor.docs.pyansys.com" ROOT = Path(".") versions = [] diff --git a/doc/source/conf.py b/doc/source/conf.py index 03645ffc..fae5bf99 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -9,7 +9,7 @@ from ansys.visor.viewer import __version__ -fallback_cname = "supreme-fiesta-v6v17mm.pages.github.io" +fallback_cname = "visor.docs.pyansys.com" cname = os.getenv("DOCUMENTATION_CNAME", fallback_cname) """The canonical name of the webpage hosting the documentation.""" From 99cabb5d0e086a7f155992cfda11a2f9d0a9758a Mon Sep 17 00:00:00 2001 From: ansbbrooks Date: Thu, 27 Aug 2026 10:35:16 -0500 Subject: [PATCH 5/6] resolve merge conflicts --- doc/source/conf.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index ee2960c6..48ff8bb8 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -64,10 +64,6 @@ "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": { # Per the Sphinx documentation: From 09cf1476f9c8e739fbefd16e5b07fb89b2388da4 Mon Sep 17 00:00:00 2001 From: ansbbrooks Date: Fri, 28 Aug 2026 13:51:02 -0500 Subject: [PATCH 6/6] using "dev" in pyproject.toml version --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index a25aac64..22367f37 100644 --- a/pyproject.toml +++ b/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 "] readme = "README.rst"