[doc-only] Guard build_docs.sh against publishing pre-release doc trees by leofang · Pull Request #3232 · NVIDIA/cuda-python

leofang · 2026-10-27T00:36:24Z

Description

Each subproject's build_docs.sh names the output subdir by importlib.metadata.version(). On a pre-release checkout that resolves to a PEP 440 .dev or +local version. When build_docs.sh is called without latest-only, that versioned subdir gets copied to latest/ and published verbatim to gh-pages, where it accumulates as an orphan tree not reachable via nv-versions.json. 26 such orphans were just purged from gh-pages at 30f5f0a — this patch keeps them from coming back.

The guard allows alpha/beta/rc tags (13.4.0b1, 1.0.0rc1, …) and only refuses .dev* and +local versions.

Checklist

New or existing tests cover these changes. (no in-repo test harness for build_docs.sh; guard logic smoke-tested locally against 1.2.1.dev249, 1.2.1+local, 1.2.1, 13.4.0b1, 13.4.1a0, 1.0.0rc1)
The documentation is up to date with these changes.

-- Leo's bot

Each subproject's build_docs.sh currently names the output subdir by importlib.metadata.version(), which on a pre-release checkout resolves to a PEP 440 .dev or +local string. When build_docs.sh is called without latest-only, that versioned subdir gets copied to latest/ and also published verbatim to gh-pages, where it accumulates as an orphan tree not reachable via nv-versions.json. Refuse that path explicitly in all three subprojects. Refs NVIDIA#3231.

copy-pr-bot · 2026-10-27T00:36:29Z

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.

coderabbitai · 2026-10-27T00:42:15Z

📝 Summary

Summary by CodeRabbit

Documentation
- Versioned documentation builds now stop with an error when the selected version includes a development or local-build marker. This prevents those builds from being copied to the latest documentation location, while builds configured for latest-only publishing are unaffected.

The CUDA Bindings 13, CUDA Core, and CUDA Pathfinder documentation build scripts now reject versioned documentation builds when the version contains .dev or +. The scripts report an error and exit before copying the versioned documentation to latest.

Changes: Versioned documentation

Layer / File(s)	Summary
Reject development versions before publication `cuda_bindings_13/docs/build_docs.sh`, `cuda_core/docs/build_docs.sh`, `cuda_pathfinder/docs/build_docs.sh`	When `LATEST_ONLY` is `0`, each script checks its version string for `.dev` or `+`. A match prints an error to stderr and exits with status 1 before copying versioned documentation to `latest`.

Possibly related PRs

NVIDIA/cuda-python#3173: Changes CUDA 12 version derivation and shared version registration for versioned documentation.
NVIDIA/cuda-python#3176: Changes version derivation and publication workflows for CUDA Bindings 13 documentation.
NVIDIA/cuda-python#3046: Changes the shared release workflow for versioned documentation.

Suggested labels: bug, CI/CD, documentation, cuda.bindings, cuda.core, cuda.pathfinder

Suggested reviewers: rwgk

Priority: Low

Change: Bug fix

Merge Risk: Moderate · up to 601e1

The new guard against publishing development-version documentation does not take effect when the version is derived by default. Dev or local builds can still be published to latest. Fix the version check before merging so it sees the raw package version.

Finishing Touches: 💡 1

🛠️ Fix failing CI checks: 💡

Commit to this branch
Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (1)

Major · Check the raw version before the default derivation strips it. · build_docs.sh:22-25

cuda_bindings_13/docs/build_docs.sh:22-25
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Check the raw version before the default derivation strips it.

important: When SPHINX_CUDA_BINDINGS_VER is unset, the default derivation reduces 13.4.0.dev1 and 13.4.0+local to 13.4.0. The publish guard never matches these versions, so pre-release builds still copy into build/html/latest. cuda_pathfinder/docs/build_docs.sh:22-25 has the same derivation and the same problem. In cuda_core/docs/build_docs.sh:22-24, awk strips only the +local suffix, so .dev versions still reach the guard but +local versions do not.

Capture the raw version before normalization, and check that value in the guard:
Suggested fix
+# Keep the raw version for the publish guard. The normalized value drops .dev and +local.
 if [[ -z "${SPHINX_CUDA_BINDINGS_VER}" ]]; then
+    RAW_BINDINGS_VER=$(python -c "from importlib.metadata import version; print(version('cuda-bindings'))")
     export SPHINX_CUDA_BINDINGS_VER=$(python -c "from importlib.metadata import version; \
                                                  ver = '.'.join(str(version('cuda-bindings')).split('.')[:3]); \
                                                  print(ver)" \
                                       | awk -F'+' '{print $1}')
+else
+    RAW_BINDINGS_VER="${SPHINX_CUDA_BINDINGS_VER}"
 fi
-    if [[ "${SPHINX_CUDA_BINDINGS_VER}" == *.dev* || "${SPHINX_CUDA_BINDINGS_VER}" == *+* ]]; then
-        echo "refusing to publish versioned docs for pre-release version '${SPHINX_CUDA_BINDINGS_VER}'" >&2
+    if [[ "${RAW_BINDINGS_VER}" == *.dev* || "${RAW_BINDINGS_VER}" == *+* ]]; then
+        echo "refusing to publish versioned docs for pre-release version '${RAW_BINDINGS_VER}'" >&2
Apply the same pattern to cuda_pathfinder/docs/build_docs.sh, using SPHINX_CUDA_PATHFINDER_VER and the cuda-pathfinder package name. Apply it to cuda_core/docs/build_docs.sh, using SPHINX_CUDA_CORE_VER and the cuda-core package name, so that +local versions are also caught.

Review info

Run configuration

Source mode: Auto
Repository: NVIDIA/cuda-python
Branch: main
File: .coderabbit.yaml
Commit: 590a8bf
Layers: Repository YAML
Review profile: CHILL
Plan: Enterprise
Run ID: 56fd6480-28ae-4c55-8123-632813ae1c41

Commits

Reviewing files that changed from the base of the PR and between 590a8bf and 601e106.

Files selected for processing: 3

cuda_bindings_13/docs/build_docs.sh
cuda_core/docs/build_docs.sh
cuda_pathfinder/docs/build_docs.sh

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

coderabbitai · 2026-10-27T00:42:18Z

+    # versions, which otherwise leak orphan trees onto gh-pages that
+    # are not reachable via nv-versions.json. See #3231.
+    if [[ "${SPHINX_CUDA_BINDINGS_VER}" == *.dev* || "${SPHINX_CUDA_BINDINGS_VER}" == *+* ]]; then
+        echo "refusing to publish versioned docs for pre-release version '${SPHINX_CUDA_BINDINGS_VER}'" >&2


Minor · Functional Correctness · Quick win

minor: Use an error message that matches the guard. The branch rejects .dev and +, but the message says “pre-release version.” The guard allows alpha, beta, and release-candidate versions. Use wording such as “development or local version” in all three scripts.

leofang · 2026-10-27T14:34:24Z

/ok to test 601e106

github-actions · 2026-10-27T14:56:37Z

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-3232/
https://nvidia.github.io/cuda-python/pr-preview/pr-3232/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-3232/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-3232/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

github-actions Bot added cuda.bindings Everything related to the cuda.bindings module cuda.core Everything related to the cuda.core module cuda.pathfinder Everything related to the cuda.pathfinder module labels Oct 27, 2026

leofang self-assigned this Oct 27, 2026

leofang added the documentation Improvements or additions to documentation label Oct 27, 2026

leofang added this to the cuda.core 1.3.0 milestone Oct 27, 2026

coderabbitai Bot reviewed Oct 27, 2026

View reviewed changes

leofang changed the title ~~Guard build_docs.sh against publishing pre-release doc trees~~ [doc-only] Guard build_docs.sh against publishing pre-release doc trees Oct 27, 2026

Navigation Menu

Repository navigation

[doc-only] Guard build_docs.sh against publishing pre-release doc trees - #3232

[doc-only] Guard build_docs.sh against publishing pre-release doc trees#3232
leofang wants to merge 1 commit into
NVIDIA:mainfrom
leofang:fix/docs-pre-release-version-guard

leofang commented Oct 27, 2026 •

edited

Loading

Uh oh!

copy-pr-bot Bot commented Oct 27, 2026

Uh oh!

coderabbitai Bot commented Oct 27, 2026 •

edited

Loading

Summary by CodeRabbit

Uh oh!

coderabbitai Bot left a comment

Uh oh!

coderabbitai Bot Oct 27, 2026

Uh oh!

leofang commented Oct 27, 2026

Uh oh!

github-actions Bot commented Oct 27, 2026

Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

leofang commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

copy-pr-bot Bot commented Oct 27, 2026

Uh oh!

coderabbitai Bot commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

leofang commented Oct 27, 2026

Uh oh!

github-actions Bot commented Oct 27, 2026

Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

leofang commented Oct 27, 2026 •

edited

Loading

coderabbitai Bot commented Oct 27, 2026 •

edited

Loading