Port RAPIDS docs from Jekyll to NVIDIA Sphinx theme

.devcontainer/devcontainer.json

@@ -1,24 +1,13 @@
-// For format details, see https://aka.ms/devcontainer.json. For config options, see the
-// README at: https://github.com/devcontainers/templates/tree/main/src/jekyll
+// For format details, see https://aka.ms/devcontainer.json.
 {
-	"name": "Jekyll",
-	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
-	"image": "mcr.microsoft.com/devcontainers/jekyll:2-bullseye",
-	"features": {
-	}
-
-	// Features to add to the dev container. More info: https://containers.dev/features.
-	// "features": {},
-
-	// Use 'forwardPorts' to make a list of ports inside the container available locally.
-	// "forwardPorts": [],
-
-	// Uncomment the next line to run commands after the container is created.
-	// "postCreateCommand": "jekyll --version"
-
-	// Configure tool-specific properties.
-	// "customizations": {},
-
-	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
-	// "remoteUser": "root"
+	"name": "RAPIDS Docs",
+	"image": "mcr.microsoft.com/devcontainers/python:3.14-bookworm",
+	"forwardPorts": [8000],
+	"portsAttributes": {
+		"8000": {
+			"label": "RAPIDS Docs",
+			"onAutoForward": "openPreview"
+		}
+	},
+	"postCreateCommand": "pipx install uv && uv sync --locked"
 }

.github/workflows/deploy.yaml

@@ -24,21 +24,21 @@ jobs:
         with:
           fetch-depth: 0
           persist-credentials: false
-      # this step uses the `.ruby-version` file
-      - uses: ruby/setup-ruby@6aaa311d81eba98ae12eaffbcb63296ace0efcde # v1.307.0
-      - name: Build Jekyll Site
-        run: |
-          bundle install
-          bundle exec jekyll build
+      - name: Set up uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --locked
+      - name: Build and validate portal
+        run: make check
       - uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708 #v5.1.1
         with:
           role-to-assume: ${{ vars.AWS_ROLE_ARN }}
           aws-region: ${{ vars.AWS_REGION }}
           role-duration-seconds: 7200 # 2h
-      - name: Fetch doc files from S3
-        run: ci/download_from_s3.sh
-      - name: Post-process docs
-        run: ci/post-process.sh
+      - name: Assemble complete documentation site
+        run: make assemble
       - name: Deploy site
         env:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_API_TOKEN }}

.github/workflows/pr.yaml

@@ -20,3 +20,30 @@ jobs:
         with:
           persist-credentials: false
       - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Set up uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --locked
+      - name: Build and validate portal
+        run: make check
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708 # v5.1.1
+        with:
+          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
+          aws-region: ${{ vars.AWS_REGION }}
+          role-duration-seconds: 7200
+      - name: Assemble and validate complete documentation site
+        run: make assemble

.gitignore

@@ -1,14 +1,7 @@
-_site/
-_sass/
-.sass-cache/
--P/
-.vscode
-lib_map.json
-.DS_Store
-files-to-customize.txt
-.jekyll-cache
-.jekyll-metadata
-.netlify
+/.ruff_cache/
+/.venv/
+/_site/
+/files-to-customize.txt
+/ci/customization/lib_map.json
 __pycache__/
-node_modules
-rapids-docs-env/
+*.pyc

.pre-commit-config.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2024-2025, NVIDIA CORPORATION.
+# Copyright (c) 2024-2026, NVIDIA CORPORATION.
 
 ci:
   autofix_commit_msg: "[pre-commit.ci] auto code formatting"

.python-version

@@ -0,0 +1 @@
+3.14

404.md

@@ -1,9 +1,6 @@
 ---
-layout: default
-permalink: /404.html
-nav_exclude: true
+orphan: true
 ---
-
 # Page Not Found
 
 We could not find the page you were looking for.
@@ -12,9 +9,9 @@ We could not find the page you were looking for.
   if (window.location.pathname.match(/^\/api.*/)) {
     var redirectEl = document.createElement("p");
     redirectEl.innerHTML = "Redirecting you to the latest documentation in 5 seconds..."
-    document.getElementById("main-content").appendChild(redirectEl);
+    (document.querySelector("article") || document.body).appendChild(redirectEl);
     setTimeout(function() {
-      window.location.href = '/api';
+      window.location.href = '/api/';
     }, 5000);
   }
 </script>

CONTRIBUTING.md

@@ -2,148 +2,91 @@
 
 ## Environment setup
 
-- Install Ruby
-- Install Bundler
-- Checkout repo
-- Run `bundle install` in checked out repo
-
-## Development
-
-```sh
-bundle exec jekyll serve
-```
-
-### Dev Containers
-
-If you're using [VSCode](https://code.visualstudio.com/) you can use the jekyll Dev Container.
-
-- This project contains a devcontainer config:
-  - If prompted with "Folder contains a Dev Container configuration file." select "Reopen in Container"
-  - Alternatively select "Dev Containers: Reopen in Container" from the command palette
-- Run `bundle exec jekyll serve`
-
-### Local Docker development
-
-Alternatively, you can use the [jekyll-docker](https://github.com/envygeeks/jekyll-docker) container to build and serve the `docs` site locally:
-
-```sh
-docker run --rm \
-  --volume="$PWD:/srv/jekyll" \
-  --publish [::1]:4000:4000 \
-  jekyll/jekyll \
-  bash -c 'rm -rf ./_site && jekyll serve'
-```
-
-### Local macOS development
-
-Upgrade to a new-enough ruby and install `jekyll`, like following https://jekyllrb.com/docs/installation/macos/
-
-```shell
-# (one-time) get ruby env-management stuff
-brew install chruby ruby-install
-
-# (one time) update to newer ruby
-ruby-install ruby 3.4.1
-
-source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh
-source $(brew --prefix)/opt/chruby/share/chruby/auto.sh
-chruby ruby-3.4.1
-ruby -v
-
-# (one time) install Bundler
-gem install bundler
-
-# install everything else the project needs
-bundle install
-```
-
-Build the site (this populates the `_site/` folder)
+Install [uv](https://docs.astral.sh/uv/), check out the repository, and install
+the locked development environment:
 
 ```shell
-bundle exec jekyll build --verbose
+uv sync --locked
 ```
 
-At this point, the API documentation will not be populated.
-
-To test those and the post-processing that happens on them, get read-only AWS credentials for the relevant resources
-and put them in a profile called `[rapids-docs]` in your AWS CLI configuration.
+Alternatively, open the repository in its development container. The container
+installs uv and the locked environment automatically.
 
-```shell
-export AWS_DEFAULT_PROFILE="rapids-docs"
-ci/download_from_s3.sh
-```
-
-At this point, the site is now built and the API documentation has been downloaded.
-Next, some post-processing needs to be done to point links like `/stable` (including those in drop-down selectors)
-to the appropriate documentation files.
+## Development
 
-Those steps include a `pip install`, so create and active a Python virtual environment first.
+Build the portal and serve the rendered site:
 
 ```shell
-python -m venv rapids-docs-env
-source ./rapids-docs-env/bin/activate
+make html
+make serve
 ```
 
-Then run the post-processing.
+The server uses port 8000 by default. Pass a different port when needed:
 
 ```shell
-ci/post-process.sh
+make serve PORT=8080
 ```
 
-At this point, you should be able to view the site locally with a pretty similar experience to what's hosted in deployments.
-
-`jekyll serve` cleans and re-generates the `_site/` folder, but it also does some other bundling and packaging that's needed for links and formatting
-to work correctly.
-
-First, back up the `api/` directory:
+Run site validation before submitting a change:
 
 ```shell
-BACKUP_DIR=$(mktemp -d)
-cp -avR ./_site/api "${BACKUP_DIR}"
+make check
 ```
 
-Then serve the site.
+This runs formatting and lint checks, unit tests, a strict Sphinx build, and
+route and rendered-content validation.
 
-```shell
-bundle exec jekyll serve
-```
+## Full documentation assembly
 
-Once it's up, copy all the `api/` files back in.
+The portal-only build does not include the versioned API documentation or the
+deployment documentation. To test the complete site and its post-processing,
+obtain read-only AWS credentials for the documentation bucket and configure an
+AWS CLI profile named `rapids-docs`. Then run:
 
 ```shell
-cp -avR "${BACKUP_DIR}/api" _site
+AWS_PROFILE=rapids-docs make full
 ```
 
-`jekyll serve` should automatically pick up the changes.
-
-In a browser, navigate to the URL shown in the `jekyll serve` output (probably something like `http://127.0.0.1:4000/`) to see the rendered docs.
-
-If the hot reloading in `jekyll serve` again deletes all the files in `api/`, just copy them in again.
+This builds the Sphinx portal into `_site`, downloads the imported
+documentation, creates the stable, latest, nightly, and legacy aliases, adds
+the RAPIDS library and version selectors, and validates the assembled site.
+Serve the result without rebuilding it with:
 
 ```shell
-cp -avR "${BACKUP_DIR}/api" _site
+make serve
 ```
 
 ## PR submissions
 
-Once you have code changes, submit a PR to the docs site. Netlify will generate
-a preview of your changes and the team will review.
+Submit changes as a pull request to `rapidsai/docs`. The RAPIDS copy-PR bot
+copies the pull request head to a `pull-request/<number>` branch in the upstream
+repository. CI validates that branch and dry-runs assembly of the complete
+S3-backed documentation site without deploying it. Netlify's repository
+integration separately creates a portal-only preview for review.
 
 ## Developer Certificate of Origin
 
-All contributions to this project must be accompanied by a sign-off indicating that the contribution is made pursuant to the Developer Certificate of Origin (DCO). This is a lightweight way for contributors to certify that they wrote or otherwise have the right to submit the code they are contributing to the project.
+All contributions to this project must be accompanied by a sign-off indicating
+that the contribution is made pursuant to the Developer Certificate of Origin
+(DCO). This is a lightweight way for contributors to certify that they wrote
+or otherwise have the right to submit the code they are contributing to the
+project.
 
-The DCO is a simple statement that you, as a contributor, have the legal right to make the contribution. To certify your adherence to the DCO, you must sign off on your commits. This is done by adding a `Signed-off-by` line to your commit messages:
+The DCO is a simple statement that you, as a contributor, have the legal right
+to make the contribution. To certify your adherence to the DCO, you must sign
+off on your commits. This is done by adding a `Signed-off-by` line to your
+commit messages:
 
-```
+```text
 Signed-off-by: Random J Developer <random@developer.example.org>
 ```
 
 You can do this automatically with `git commit -s`.
 
-Here is the full text of the DCO, which you can also find at <https://developercertificate.org/>:
+Here is the full text of the DCO, which you can also find at
+<https://developercertificate.org/>:
 
-```
+```text
 Developer's Certificate of Origin 1.1
 
 By making a contribution to this project, I certify that: