Switch to nvidia-sphinx-theme with backward-compatible version switching (#874)

* Initial plan

* Switch to nvidia-sphinx-theme and update version JSON format

Co-authored-by: leofang <5534781+leofang@users.noreply.github.com>

* Temporarily disable test jobs in CI, keeping only wheel build and doc jobs

Co-authored-by: leofang <5534781+leofang@users.noreply.github.com>

* Address PR feedback: Fix CI workflow and preserve original versions.json files

- Modify CI workflow to only comment out test-linux/test-windows in needs section instead of entire status check job
- Revert all versions.json files to original format for backward compatibility
- Create new nv-versions.json files with new format for nvidia-sphinx-theme
- Update sphinx config files to reference new nv-versions.json files

Co-authored-by: leofang <5534781+leofang@users.noreply.github.com>

* Fix sphinx version constraint to resolve nvidia-sphinx-theme CI failure

Co-authored-by: leofang <5534781+leofang@users.noreply.github.com>

* Revert sphinx version constraint changes from commit c72a6b2

Co-authored-by: leofang <5534781+leofang@users.noreply.github.com>

* Comment out proxy cache in docs build to debug nvidia-sphinx-theme installation

Co-authored-by: leofang <5534781+leofang@users.noreply.github.com>

* Revert ci.yml changes and remove proxy cache from build-docs.yml

Co-authored-by: leofang <5534781+leofang@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: leofang <5534781+leofang@users.noreply.github.com>

Author: Copilot

.github/workflows/build-docs.yml

@@ -52,9 +52,7 @@ jobs:
           fetch-depth: 0
           ref: ${{ inputs.git-tag }}
 
-      - name: Setup proxy cache
-        uses: nv-gha-runners/setup-proxy-cache@main
-        continue-on-error: true
+      # TODO: This workflow runs on GH-hosted runner and cannot use the proxy cache
 
       - name: Set up miniforge
         uses: conda-incubator/setup-miniconda@835234971496cad1653abb28a638a281cf32541f  # v3.2.0

cuda_bindings/docs/nv-versions.json

@@ -0,0 +1,30 @@
+[
+    {
+        "version": "latest",
+        "url": "https://nvidia.github.io/cuda-python/cuda-bindings/latest/"
+    },
+    {
+        "version": "13.0.1",
+        "url": "https://nvidia.github.io/cuda-python/cuda-bindings/13.0.1/"
+    },
+    {
+        "version": "13.0.0",
+        "url": "https://nvidia.github.io/cuda-python/cuda-bindings/13.0.0/"
+    },
+    {
+        "version": "12.9.0",
+        "url": "https://nvidia.github.io/cuda-python/cuda-bindings/12.9.0/"
+    },
+    {
+        "version": "12.8.0",
+        "url": "https://nvidia.github.io/cuda-python/cuda-bindings/12.8.0/"
+    },
+    {
+        "version": "12.6.2",
+        "url": "https://nvidia.github.io/cuda-python/cuda-bindings/12.6.2/"
+    },
+    {
+        "version": "12.6.1",
+        "url": "https://nvidia.github.io/cuda-python/cuda-bindings/12.6.1/"
+    }
+]

cuda_bindings/docs/source/_static/javascripts/version_dropdown.js

@@ -59,27 +59,17 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_baseurl = "docs"
-html_theme = "furo"
-# html_theme = 'pydata_sphinx_theme'
+html_theme = "nvidia_sphinx_theme"
 html_theme_options = {
-    "light_logo": "logo-light-mode.png",
-    "dark_logo": "logo-dark-mode.png",
-    # For pydata_sphinx_theme:
-    # "logo": {
-    #    "image_light": "_static/logo-light-mode.png",
-    #    "image_dark": "_static/logo-dark-mode.png",
-    # },
-    # "switcher": {
-    #    "json_url": "https://nvidia.github.io/cuda-python/cuda-bindings/versions.json",
-    #    "version_match": release,
-    # },
-    ## Add light/dark mode and documentation version switcher
-    # "navbar_end": [
-    #    "search-button",
-    #    "theme-switcher",
-    #    "version-switcher",
-    #    "navbar-icon-links",
-    # ],
+    "switcher": {
+        "json_url": "https://nvidia.github.io/cuda-python/cuda-bindings/nv-versions.json",
+        "version_match": release,
+    },
+    # Add light/dark mode and documentation version switcher
+    "navbar_center": [
+        "version-switcher",
+        "navbar-nav",
+    ],
 }
 if os.environ.get("CI"):
     if int(os.environ.get("BUILD_PREVIEW", 0)):

cuda_bindings/docs/source/_templates/sidebar/variant-selector.html

@@ -0,0 +1,30 @@
+[
+    {
+        "version": "latest",
+        "url": "https://nvidia.github.io/cuda-python/cuda-core/latest/"
+    },
+    {
+        "version": "0.3.2",
+        "url": "https://nvidia.github.io/cuda-python/cuda-core/0.3.2/"
+    },
+    {
+        "version": "0.3.1",
+        "url": "https://nvidia.github.io/cuda-python/cuda-core/0.3.1/"
+    },
+    {
+        "version": "0.3.0",
+        "url": "https://nvidia.github.io/cuda-python/cuda-core/0.3.0/"
+    },
+    {
+        "version": "0.2.0",
+        "url": "https://nvidia.github.io/cuda-python/cuda-core/0.2.0/"
+    },
+    {
+        "version": "0.1.1",
+        "url": "https://nvidia.github.io/cuda-python/cuda-core/0.1.1/"
+    },
+    {
+        "version": "0.1.0",
+        "url": "https://nvidia.github.io/cuda-python/cuda-core/0.1.0/"
+    }
+]

cuda_bindings/docs/source/conf.py

@@ -56,27 +56,17 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_baseurl = "docs"
-html_theme = "furo"
-# html_theme = 'pydata_sphinx_theme'
+html_theme = "nvidia_sphinx_theme"
 html_theme_options = {
-    "light_logo": "logo-light-mode.png",
-    "dark_logo": "logo-dark-mode.png",
-    # For pydata_sphinx_theme:
-    # "logo": {
-    #    "image_light": "_static/logo-light-mode.png",
-    #    "image_dark": "_static/logo-dark-mode.png",
-    # },
-    # "switcher": {
-    #    "json_url": "https://nvidia.github.io/cuda-python/cuda-core/versions.json",
-    #    "version_match": release,
-    # },
-    ## Add light/dark mode and documentation version switcher
-    # "navbar_end": [
-    #    "search-button",
-    #    "theme-switcher",
-    #    "version-switcher",
-    #    "navbar-icon-links",
-    # ],
+    "switcher": {
+        "json_url": "https://nvidia.github.io/cuda-python/cuda-core/nv-versions.json",
+        "version_match": release,
+    },
+    # Add light/dark mode and documentation version switcher
+    "navbar_center": [
+        "version-switcher",
+        "navbar-nav",
+    ],
 }
 if os.environ.get("CI"):
     if int(os.environ.get("BUILD_PREVIEW", 0)):

cuda_core/docs/nv-versions.json

@@ -15,8 +15,9 @@ dependencies:
   - scipy
   - sphinx <8.2.0
   - sphinx-copybutton
-  - furo
   - myst-nb
   - enum_tools
   - sphinx-toolbox
   - pyclibrary
+  - pip:
+    - nvidia-sphinx-theme