[leofang]

Description

Refs #3231

Rework per @juenglin's review on the previous revision.

ci.yml runs build-docs.yml on every v*, cuda-core-v*, and cuda-pathfinder-v* tag push with is-release: true and the default component: all, which previously also deployed every subproject's versioned docs. On any tag push, subprojects that happen to be on a .dev wheel at that moment land under truncated clean-looking X.Y.Z names on gh-pages (build_docs.sh strips the .dev suffix for cuda-bindings and cuda-pathfinder; cuda-core preserves it). That's the mechanism behind every orphan tree purged at 30f5f0a and 7d206dd.

This PR adds one line to ci.yml:

     with:
       is-release: ${{ github.ref_type == 'tag' }}
+      deploy-docs: ${{ github.ref_type != 'tag' }}

Tag CI still validates the release build path (the "Upload dry-run docs artifact" step keeps the output inspectable). release.yml continues to drive the actual release deploy, component-scoped. This stops .devN, aN, bN, rcN, truncated X.Y.Z, and the latest//nv-versions.json overwrites in one place, regardless of version-string format.

Previous revision added guards to each subproject's build_docs.sh; those guards (a) didn't fire for cuda-bindings or cuda-pathfinder because the derivation strips .dev before the check, and (b) would have failed every tag CI run under set -e. Dropped.

Checklist

• New or existing tests cover these changes. (no behavior change to tested code; one YAML input to a reusable workflow)
• The documentation is up to date with these changes.

-- Leo's bot

[copy-pr-bot]

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]

📝 Summary

Summary by CodeRabbit

• Chores
  • Documentation deployments now run for non-tag builds. Tag builds no longer trigger a documentation deployment. This changes when documentation is published through the build process; it does not change the documentation content or features available in the product.

The doc workflow call sets deploy-docs to false for tag refs and true for non-tag refs.

Changes: Documentation workflow

Layer / File(s)	Summary
Set deployment flag by ref type .github/workflows/ci.yml	The doc workflow call sets deploy-docs based on whether the ref is a tag.

Suggested labels: CI/CD, github_actions

Suggested reviewers: rwgk

Priority: Low

Change: Bug fix

Merge Risk: Minimal · up to 3fd64

This change stops CI runs on tag pushes from publishing docs, while release docs are published through the separate manual release workflow. No concrete merge-blocking problem was established. The PR description mentions a build_docs.sh guard that is not part of this head, which the author may want to clarify.

- [ ] 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.

[leofang]

/ok to test 601e106

[github-actions]

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.

[juenglin]

Thanks for picking this up. Keeping orphan trees off gh-pages is worth guarding. Tracing where the orphans come from, though, points to a different root cause. It also suggests this guard would break tag CI.

Where the orphan trees come from

ci.yml runs on every tag push (v*, cuda-core-v*, cuda-pathfinder-v*) and calls build-docs.yml with is-release: true. It doesn't pass component, so that defaults to all, and deploy-docs defaults to true. Tag CI therefore runs build_all_docs.sh without latest-only and deploys every package's versioned tree to gh-pages. Only the tagged package has an exact version; the others are built from dev wheels.

Example: the cuda-pathfinder-v1.8.4 tag push (run 39832572216, 18:34 UTC on Oct 22) produced gh-pages commit 7125843 at 18:52, "Deploy release docs: cuda-pathfinder-v1.8.4". That commit added cuda-core/1.2.1.dev249 and cuda-bindings/13.4.4. It also overwrote cuda-core/latest, cuda-bindings/latest and cuda-pathfinder/nv-versions.json. The actual release.yml run for that tag (run 39859618232, 21:44) built only the pathfinder docs.

I traced 9 of the 26 trees purged at 30f5f0a. Six were added by "Deploy release docs: cuda-pathfinder-v…" commits (v1.5.6, v1.6.0, v1.8.0, v1.8.2, v1.8.3, v1.8.4). The three oldest (0.5.1.dev132, 0.6.1.dev36, 0.7.1.dev62, Feb to Apr) were added by deploys with an empty ref.

The same path also publishes alpha and beta trees. cuda-bindings/13.4.1a0 was added by "Deploy release docs: v13.4.1a0" at 23:14 UTC on Sep 9. That was while the tag CI run (34414563265) was in progress, and before any release.yml run that day. aN tags are now reserved for internal milestones (AGENTS.md, #2932), but this one became public docs. cuda-bindings/13.4.0b1 is also on gh-pages. Neither is listed in cuda-bindings/nv-versions.json.

What this PR would do in that setup

• On any v* or cuda-pathfinder-v* tag, cuda-core is a dev version, so the cuda_core guard exits 1. build_all_docs.sh runs under set -e, so the docs job and the whole tag CI run fail.
• release.yml auto-detects "the successful CI run triggered by a tag push" through ci/tools/lookup-run-id. So this would block bindings, cuda-python and pathfinder releases unless someone supplies a run ID by hand.
• On cuda-core-v* tags the guard never fires (see below), so the other packages keep leaking.
• The guard doesn't catch aN, bN or rcN versions. Since #2922 switched to default setuptools-scm tag parsing, rc suffixes are no longer stripped. The next bindings rc tag would publish a 13.x.0rcN tree.
• The latest/ and nv-versions.json overwrites aren't addressed.

Suggested fix

release.yml already builds and deploys release docs, scoped to the component being released. Tag CI only needs to build the docs, not deploy them:

uses: ./.github/workflows/build-docs.yml
with:
  is-release: ${{ github.ref_type == 'tag' }}
  deploy-docs: ${{ github.ref_type != 'tag' }}

This still validates the release build path on every tag, and the existing "Upload dry-run docs artifact" step keeps the output inspectable. The deploy job itself still runs on every push to main. The change stops every leak above regardless of version format: .devN, aN, bN and rcN trees, truncated X.Y.Z trees, and the latest/ and nv-versions.json overwrites.

Possible follow-up: tag CI uses the "Build all docs" path, but release.yml always uses "Build component docs", since all isn't a release option. Passing the component that matches the tag namespace would make tag CI validate exactly what the release runs.

If a build_docs.sh guard is kept as a backstop

• Scope it to the package being released. Otherwise it causes the tag CI failure above.
• Allow only plain X.Y.Z, rather than rejecting known pre-release patterns. Tag formats have changed recently (#2922, #2932), and a pattern list like *.dev* falls behind each time.
• Check the version before it is truncated or stripped. The current check misses most cases:
  1. cuda_bindings_13, cuda_pathfinder and cuda_python keep only three version fields ('.'.join(...split('.')[:3])). So 1.2.1.dev249 becomes 1.2.1, and 13.4.1a1.dev5 becomes 13.4.1a1; both pass. Clean-looking trees already leaked this way. They're unlisted in nv-versions.json and have no matching tag: cuda-bindings/13.1.2, 13.2.1, 13.3.2 and cuda-pathfinder/1.5.7. They sit where the real release would later go.
  2. All scripts strip +local with awk -F'+' before the check, so the *+* branch can never match.
• Test it against the real derivation. The smoke test checked the pattern on literal strings. ci/tools/tests/test_build_docs_for_link_check.py is a precedent for pytest-driven tests of docs shell scripts.
• Cover cuda_python/docs/build_docs.sh as well.
• (nit) Fail before make html.

Separately, the unlisted trees above (13.4.1a0, 13.4.0b1 and the clean-looking ones) may be worth purging.

[coderabbitai]

Additional comments: 1

.github/workflows/ci.yml-634-634: 1

634-634: Major · Functional Correctness · Quick win

Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

important: Keep deploy-docs enabled for release tags. build-docs.yml gates both the deployment job and the release documentation update on inputs.deploy-docs; this expression is false when github.ref_type == 'tag', even though the same workflow sets is-release to true. Tag builds therefore produce release documentation without publishing it. Apply the .dev and +local guard in build_docs.sh instead of disabling deployment for every tag.

The workflow contract and PR objective establish this impact.
As per path instructions, this checks deployment gating and release behavior.

Source: Path instructions

---

Review info

Run configuration

• Source mode: Auto
• Repository: NVIDIA/cuda-python
• Branch: main
• File: .coderabbit.yaml
• Commit: 3cc4edb
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 6071f026-8379-4767-bb66-709b0462ad93

Commits

Reviewing files that changed from the base of the PR and between 601e106 and 3fd6462.

Files selected for processing: 1

• .github/workflows/ci.yml

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

[leofang]

/ok to test 3fd6462

[leofang]

Thanks, Ralf, for careful review! My bot was completely off.