Port RAPIDS docs from Jekyll to NVIDIA Sphinx theme by bdice · Pull Request #807 · rapidsai/docs

bdice · 2026-07-06T23:24:56Z

Summary

port the RAPIDS documentation portal from Jekyll to Sphinx, MyST, and the NVIDIA Sphinx theme
preserve the published routes, notices, release and platform data, installation selector, visualizations, redirects, RSS feed, and production telemetry
adapt the S3 assembly and post-processing pipeline to the locked uv environment and add Netlify previews for copied pull request branches

Validation

pre-commit run --all-files
pytest (3 tests passed)
strict Sphinx dirhtml build with warnings treated as errors (129 sources)
rendered-site validation (132 HTML files and 94 notices)
route and heading comparison against the Jekyll baseline (128 routes)

The S3-backed full-site assembly and Netlify preview run in the upstream deploy workflow after the copy-PR bot creates the pull-request/<number> branch.

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

netlify · 2026-07-06T23:33:56Z

✅ Deploy Preview for docs-rapids-ai ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`c03a97a`
🔍 Latest deploy log	https://app.netlify.com/projects/docs-rapids-ai/deploys/6a5515ce7f624b0008cf5f65
😎 Deploy Preview	https://deploy-preview-807--docs-rapids-ai.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Restore development support and minimize migration diff

copy-pr-bot · 2026-07-07T01:29:53Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice · 2026-07-07T01:36:29Z

/ok to test 0531a34

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice · 2026-07-07T01:45:22Z

/ok to test ad33396

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice · 2026-07-07T01:47:13Z

/ok to test 61cb205

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice · 2026-07-07T01:51:35Z

/ok to test 32fa1c9

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Keep portal content at repository root

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice · 2026-07-07T02:06:25Z

/ok to test 6166ae2

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice · 2026-07-07T02:09:59Z

/ok to test c1e649e

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Refine install selector spacing

Split RAPIDS docs extension into modules

Restore notice status labels

https://github.com/rapidsai/cuxfilter is now archived and the 26.06 release is done. The RSN about archiving `cuxfilter` can be marked complete. Authors: - James Lamb (https://github.com/jameslamb) Approvers: - Bradley Dice (https://github.com/bdice) URL: rapidsai#808 (cherry picked from commit ff3968c) Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Contributes to rapidsai/build-planning#291 * moves `cuxfilter` to the "inactive projects' section of the API docs * removes references encouraging its use Authors: - James Lamb (https://github.com/jameslamb) Approvers: - Bradley Dice (https://github.com/bdice) URL: rapidsai#809 (cherry picked from commit 922b693) Signed-off-by: Bradley Dice <bdice@bradleydice.com>

## Summary - Removes TensorFlow from the install selector's **Additional Packages** options and deletes obsolete compatibility notes. - Allows PyTorch to be selected with CUDA 13. I validated that current official PyTorch wheels and conda-forge packages support CUDA 13. Authors: - Bradley Dice (https://github.com/bdice) Approvers: - James Lamb (https://github.com/jameslamb) URL: rapidsai#811 (cherry picked from commit 792777e) Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Sync changes from the Jekyll site

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

mmccarty · 2026-07-13T14:48:43Z

Thanks for putting this migration together. I checked out the branch and ran the local validation successfully:

make check
Ruff lint and formatting
10 pytest tests
strict Sphinx build across 129 sources
site validation across 132 HTML files and 94 notices

I found two link regressions that the current validator does not catch:

The release links on the Platform Support page point to nonexistent anchors.

extensions/rapids_docs/platform_support.py generates targets such as #rapids-2606, but MyST generates IDs such as #rapids-26-06 and #rapids-26-08-nightly. As a result, all eight release jump links at the top of the page are broken.
Three relative Markdown links are emitted as .md URLs.

With myst_all_links_external = True, these links are preserved verbatim instead of being converted to their published routes:
- resources/merge-barriers.md → ./recently-updated.md
- resources/recently-updated.md → ./merge-barriers.md
- resources/reproducing-ci.md → ./github-actions.md
In the generated site, these resolve below the current pretty-URL directory and return 404s. Using root-relative published URLs such as /resources/recently-updated/ would fix them.

One CI follow-up: the current head (6d8ffae) has not run the S3-backed copied-branch workflow. The latest run I found was against c1e649e, where full-site assembly failed because Liquid syntax remained in three imported files. The current validator may address that, but it would be good to trigger /ok to test 6d8ffae so the latest full-site assembly is verified before merging.

Signed-off-by: Mike McCarty <mmccarty@nvidia.com>

mmccarty · 2026-07-13T16:47:14Z

The TOC on the page and in the right nav menu seems redundant with the new theme. If others agree, I can remove the hard coded TOC in install/index.md

jameslamb

This PR is way too large to review thoroughly and I know it was mostly AI-generated, so I'm treating the PR as a request like "trust me". I do trust you and that you've done some local testing, so I'm clicking "Approve" so you have what you minimally need to merge this. I support the overall intent (switching from a Jekyll site to a Sphinx one to make using the NVIDIA Sphinx theme easier).

More notes below.

Reviewing the intent

If I understand it, the reason for this goes like this:

we want to (have to?) move to the NVIDIA theme
that is published as a Sphinx theme via a Python package, so it's convenient (required?) to switch from a Jekyll site to one built with Sphinx

If I'm right about that, then totally supportive of making the switch in general. It'd help maintainability too... there are many more folks in RAPIDS who are knowledgeable about Python / Sphinx than there are who can help with Ruby / Jekyll.

Reviewing the code

I did a review pass and noted some things that I think should be addressed before merging, but based on clicking around the preview it does look like the site content and look and feel are working. API docs still do not work in the preview (#680) so we'll have to merge this and do a real deployment to be sure the changes to the post-processing are working, but your local testing makes me confident that this is at least close.

IMO this diff didn't have to be this large.

Any of these would have been quick approvals, could have been merged independently, and would have shrunk the diff here:

deleting unused files like _drafts and _includes/gpu-labels-table*
moving _notices/* to notices/
adding pyproject.toml with ruff rules and reformatting existing files based on those rules
updates to copyright dates on otherwise-unchanged files
minor formatting changes like removing the unnecessary ** in section headers in install/index.md

But we're here now and I've reviewed them, so fine to just leave them all in.

jameslamb · 2026-07-13T16:04:35Z

+name = "rapids-docs"
+version = "0.1.0"
+description = "NVIDIA RAPIDS documentation portal"
+requires-python = ">=3.12"


Suggested change

requires-python = ">=3.12"

requires-python = ">=3.14"

Since .python-version points to 3.14 and other files like the uv.lock match that, let's just make this >=3.14. This is an application, not a library, it only needs to support a single Python version at a time and we might as well make it a new one.

jameslamb · 2026-07-13T16:05:30Z

+    "pre-commit>=4.2.0",
+    "pytest>=8.4.0",
+    "ruff>=0.12.0",
+]


Suggested change

]

As far as I can tell, this dev group has no purpose. I don't see it used anywhere. Let's remove it and the need to ever think about updating it.

jameslamb · 2026-07-13T16:05:37Z

+
+[tool.ruff]
+line-length = 100
+target-version = "py312"


Suggested change

target-version = "py312"

target-version = "py314"

jameslamb · 2026-07-13T16:07:21Z

+- Portal content, data, includes, and assets retain their established paths at
+  the repository root.


Suggested change

- Portal content, data, includes, and assets retain their established paths at

the repository root.

This is the type of thing an LLM likes to write at the end of making a change for you but has no place in these docs. If I just git clone'd this repo to work on it, what does it even mean to me that these directories "retain their established paths"?

Remove this, and please do a pass of review yourself for similar LLM artifacts, if you haven't already.

jameslamb · 2026-07-13T16:10:02Z

+- Portal content, data, includes, and assets retain their established paths at
+  the repository root.
+- `sphinx/` contains the Sphinx configuration, templates, and theme overrides.
+- `extensions/` contains the portal's data-rendering and publication extension.


Suggested change

- `extensions/` contains the portal's data-rendering and publication extension.

- `extensions/` contain custom code extending Sphinx in this-project-specific ways

This statement as written doesn't really make sense to me (e.g. what is the "publication" extension? We're using the third-party Netlify service to publish.) and anyway is likely to become outdated as code in extensions/ changes. Recommending a more future-proof description here.

jameslamb · 2026-07-13T16:20:20Z


 def customize_manifest_file(filepath: str) -> None:
    """Customizes one HTML file from the generated manifest."""
+    if Path(filepath).parts[-2:] == ("api", "index.html"):


Suggested change

if Path(filepath).parts[-2:] == ("api", "index.html"):

# the top-level file for the entire API docs page is known not to be one-library-specific,

# can skip processing it

if Path(filepath).parts[-2:] == ("api", "index.html"):

Is this comment accurate? If so can you please add it?

This addition looked pretty strange to me and it took me a bit to figure out why it was added.

jameslamb · 2026-07-13T16:21:50Z


 CURRENT_DIR=$(dirname $(realpath $0))

-pip install -r "${CURRENT_DIR}/customization/requirements.txt"


If we're not going to need this requirements.txt file any more then this PR should delete it, please.

jameslamb · 2026-07-13T16:31:50Z

+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
+# SPDX-License-Identifier: Apache-2.0
+
+"""One-time content migration from the pinned RAPIDS Jekyll snapshot."""


Does this really need to live in the repo? It looks to me like maybe it was an artifact of the development process you used to create this branch.

jameslamb · 2026-07-13T16:37:15Z

+project = "NVIDIA RAPIDS Documentation"
+html_title = project
+author = "NVIDIA"
+copyright = f"{datetime.date.today().year}, NVIDIA"


Suggested change

copyright = f"{datetime.date.today().year}, NVIDIA"

copyright = f"2019-{datetime.date.today().year}, NVIDIA"

This is the copyright date for the entire docs site, not just the conf.py file, isn't it? Some of the files date back to 2019, so I think we should have a a range beginning in 2019 here.

jameslamb · 2026-07-13T16:48:27Z

-_site/
-_sass/
-.sass-cache/
-P/
-.vscode
-lib_map.json
-.DS_Store
-files-to-customize.txt
-.jekyll-cache
-.jekyll-metadata
-.netlify


Why are all of these entries being deleted?

I strongly suspect you didn't do this part manually, because I doubt we now suddenly do want to check into source control things like .DS_Store files created by someone opening the project on a Mac.

Can you please do a manual pass review pass over these?

Port RAPIDS docs from Jekyll to Sphinx

0b56d47

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice added improvement non-breaking DO NOT MERGE labels Jul 6, 2026

Use configured AWS credentials for docs assembly

6853185

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice changed the title ~~Port RAPIDS docs from Jekyll to Sphinx~~ [Proof of Concept] Port RAPIDS docs from Jekyll to Sphinx Jul 6, 2026

Configure Netlify Sphinx previews

75ced39

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Restore development setup and minimize migration diff

b9828ac

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice mentioned this pull request Jul 6, 2026

Restore development support and minimize migration diff bdice/docs#1

Merged

bdice added 3 commits July 6, 2026 20:25

Use Python 3.14 for docs builds

833aeaf

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Use Python 3.14 for development

0df55ef

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Merge pull request #1 from bdice/fix/sphinx-devcontainer-cleanup

dc33cc3

Restore development support and minimize migration diff

Build complete site in pull request CI

0531a34

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice added 2 commits July 7, 2026 01:44

Keep portal content at repository root

b4bde80

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Use standard Jinja template syntax

ad33396

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Skip portal API page during docs customization

61cb205

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice added 2 commits July 7, 2026 01:48

Remove Jekyll parity fixture

4d49de0

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Keep pull request builds deployment-free

32fa1c9

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice added 3 commits July 7, 2026 01:53

Merge sphinx-port into root-source layout

3ffde60

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Merge pull request #2 from bdice/refactor/root-sphinx-source

22cd055

Keep portal content at repository root

Improve API documentation layout

6166ae2

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Use full-width API documentation cards

c1e649e

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

bdice added 6 commits July 7, 2026 02:14

Refine install selector spacing

2c791cc

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Split RAPIDS docs extension into modules

9f1e7f6

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Restore notice status labels

50032db

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Merge pull request #3 from bdice/fix/install-selector-spacing

3166ccf

Refine install selector spacing

Merge pull request #4 from bdice/refactor/split-rapids-docs-extension

03687d0

Split RAPIDS docs extension into modules

Merge pull request #5 from bdice/fix/notice-status-labels

76ee9c9

Restore notice status labels

bdice changed the title ~~[Proof of Concept] Port RAPIDS docs from Jekyll to Sphinx~~ Port RAPIDS docs from Jekyll to NVIDIA Sphinx theme Jul 12, 2026

Cleanup

41887bb

bdice marked this pull request as ready for review July 12, 2026 15:20

bdice requested a review from a team as a code owner July 12, 2026 15:20

jameslamb and others added 4 commits July 12, 2026 10:25

Merge pull request #6 from bdice/sync/jekyll-upstream

fa046a1

Sync changes from the Jekyll site

bdice self-assigned this Jul 12, 2026

bdice added breaking feature request New feature or request and removed DO NOT MERGE non-breaking improvement labels Jul 12, 2026

Merge upstream/main into sphinx-port

6d8ffae

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

This was referenced Jul 12, 2026

Source install selector from platform support data #802

Open

Highlight additional Conda package names separately #805

Open

Use concise site navigation titles

c03a97a

Signed-off-by: Mike McCarty <mmccarty@nvidia.com>

jameslamb approved these changes Jul 13, 2026

View reviewed changes

		- Portal content, data, includes, and assets retain their established paths at
		the repository root.

	- `extensions/` contains the portal's data-rendering and publication extension.
	- `extensions/` contain custom code extending Sphinx in this-project-specific ways


		CURRENT_DIR=$(dirname $(realpath $0))

		pip install -r "${CURRENT_DIR}/customization/requirements.txt"

	copyright = f"{datetime.date.today().year}, NVIDIA"
	copyright = f"2019-{datetime.date.today().year}, NVIDIA"

Uh oh!

Conversation

bdice commented Jul 6, 2026

Summary

Validation

Uh oh!

netlify Bot commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docs-rapids-ai ready!

Uh oh!

copy-pr-bot Bot commented Jul 7, 2026

Uh oh!

bdice commented Jul 7, 2026

Uh oh!

bdice commented Jul 7, 2026

Uh oh!

bdice commented Jul 7, 2026

Uh oh!

bdice commented Jul 7, 2026

Uh oh!

bdice commented Jul 7, 2026

Uh oh!

bdice commented Jul 7, 2026

Uh oh!

mmccarty commented Jul 13, 2026

Uh oh!

mmccarty commented Jul 13, 2026

Uh oh!

jameslamb left a comment

Choose a reason for hiding this comment

Reviewing the intent

Reviewing the code

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify Bot commented Jul 6, 2026 •

edited

Loading