Skip to content

[docs] Unpin breathe now that 5.1.0 fixes template specialization names - #12307

Merged
bernhardmgruber merged 3 commits into
NVIDIA:mainfrom
KassaSana:docs/unpin-breathe
Nov 2, 2026
Merged

[docs] Unpin breathe now that 5.1.0 fixes template specialization names#12307
bernhardmgruber merged 3 commits into
NVIDIA:mainfrom
KassaSana:docs/unpin-breathe

Conversation

@KassaSana

@KassaSana KassaSana commented Oct 28, 2026

Copy link
Copy Markdown
Contributor

Description

closes #11777

#11582 pinned breathe<5 because breathe 5.0.0 dropped template arguments from class template specialization names, crashing Sphinx's C++ domain (assert parent_symbol) and hanging the docs job. The fix (breathe-doc/breathe#1085) shipped in breathe 5.1.0, so this requires breathe>=5.1.0.

Verification

Built the full docs locally (docs/gen_docs.bash, Doxygen 1.9.6, Sphinx 9.1.1, -W --keep-going, -j auto) on main with breathe 4.36.0 and on this branch with breathe 5.1.0, then compared the output:

  • Both builds succeed with no Sphinx warnings, and there's no crash or hang. The breathe 5.1.0 build was faster: 316 s vs 559 s, though the 559 s includes compiling Doxygen, which only happens on the first run.
  • Both builds generate the same 1769 HTML pages with the same 7338 C++ anchors.
  • All 71 class template specialization pages are identical in visible text, template arguments included.
  • In a random sample of 300 API pages, 16 differ in visible text:
    • Improvements:
      • Inline parameter references now render. The ShuffleDown docs read "warp-lane i + src_offset" where they used to read "warp-lane + .".
      • 21 pages that showed a literal &#8212; now render the dash.
    • Regressions:
      • constexpr is missing from 21 member signatures across 12 pages, for example cuda::pinned_memory_pool::release, cuda::event and cuda::get_stream_t. Doxygen 1.9.6 leaves constexpr in <type> without setting constexpr="yes". Since breathe 5 (as part of the fix for Breathe 5.0.0 duplicates constexpr on constructors, producing invalid C++ declarations breathe-doc/breathe#1081), breathe strips constexpr from the type and re-adds it only from that attribute. Newer Doxygen sets the attribute.
      • In 12 of 35 pages, code snippets lose the spaces before a trailing comment (#include <cub/cub.cuh>// or equivalently ...). This is cosmetic.

These regressions could be fixed separately by bumping the pinned Doxygen, or upstream in breathe. I'm happy to open follow-up issues if that's useful.

Checklist

  • New or existing tests cover these changes. (The docs build is the test.)
  • The documentation is up to date with these changes.

@KassaSana
[docs] Unpin breathe now that 5.1.0 fixes template specialization names
4a09243 
breathe 5.0.0 dropped template arguments from class template
specialization names, which crashed Sphinx's C++ domain and led to the
`<5` pin in NVIDIA#11582. The fix (breathe-doc/breathe#1085) shipped in
breathe 5.1.0, so require that release instead.

Closes NVIDIA#11777
Copilot AI balanced review requested due to automatic review settings October 28, 2026 01:13
@KassaSana
KassaSana requested a review from a team as a code owner October 28, 2026 01:13
@copy-pr-bot

copy-pr-bot Bot commented Oct 28, 2026

Copy link
Copy Markdown
Contributor

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.

@KassaSana
KassaSana requested a review from ericniebler October 28, 2026 01:13
@github-project-automation github-project-automation Bot moved this to Todo in CCCL Oct 28, 2026
Copilot AI reviewed Oct 28, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

@cccl-authenticator-app cccl-authenticator-app Bot moved this from Todo to In Review in CCCL Oct 28, 2026
@coderabbitai

coderabbitai Bot commented Oct 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

Run configuration
  • Source mode: Auto
  • Repository: NVIDIA/cccl
  • Branch: main
  • File: .coderabbit.yaml
  • Commit: eaf7eb1
  • Layers: Repository YAML
  • Review profile: CHILL
  • Plan: Enterprise
  • Run ID: 69832495-2bf0-462f-b1f6-f75e6d98fcb2
Commits

Reviewing files that changed from the base of the PR and between ed619dd and 366f1c0.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: NVIDIA/cccl
  • Branch: main
  • File: .coderabbit.yaml
  • Commit: f1b40ea
  • Layers: Repository YAML
  • Review profile: CHILL
  • Plan: Enterprise
  • Run ID: b7ed6f69-c85e-4949-9f8c-d5df550a4f1c
Commits

Reviewing files that changed from the base of the PR and between f1b40ea and 4a09243.

Files selected for processing: 1
  • docs/requirements.txt

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

📝 Summary

Summary by CodeRabbit

  • Documentation
    • Updated the setup requirements for building project documentation. This change is limited to the documentation environment and does not alter product features, workflows, or behavior. No user-facing functionality changed in this update, and no additional product changes are included.

The documentation requirements now specify Breathe version 5.1.0 or later and no longer set an upper version bound.

Changes: Breathe requirement

Layer / File(s) Summary
Update Breathe version requirement
docs/requirements.txt		 The Breathe requirement changed to >=5.1.0, with no upper version bound.

Assessment against linked issues

Objective Addressed Explanation
Remove the Breathe <5 restriction after the fix is released [11777] ✅

Suggested reviewers: bernhardmgruber

Priority: Low

Change: Other

Merge Risk: Minimal · previous review 4a092

No actionable merge-blocking risk remains in this dependency update.

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

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

@miscco

miscco commented Oct 28, 2026

Copy link
Copy Markdown
Contributor

/ok to test ed619dd

@miscco

miscco commented Oct 29, 2026

Copy link
Copy Markdown
Contributor

/ok to test 366f1c0

@miscco

miscco commented Oct 29, 2026

Copy link
Copy Markdown
Contributor

@KassaSana please do not merge main unless there are merge conflicts. There is no reason to restart CI

@KassaSana

KassaSana commented Oct 29, 2026

Copy link
Copy Markdown
Contributor Author

@KassaSana please do not merge main unless there are merge conflicts. There is no reason to restart CI

Noted !

@bernhardmgruber
bernhardmgruber merged commit ea9c434 into NVIDIA:main Nov 2, 2026
23 checks passed
@github-project-automation github-project-automation Bot moved this from In Review to Done in CCCL Nov 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@miscco miscco miscco approved these changes
@ericniebler ericniebler Awaiting requested review from ericniebler ericniebler is a code owner automatically assigned from NVIDIA/cccl-codeowners

Assignees

No one assigned

Labels

None yet

Projects

CCCL
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Unpin breathe<5 once breathe-doc/breathe#1085 is released

4 participants

@KassaSana @miscco @bernhardmgruber