Doc issues fail CI by alliepiper · Pull Request #8161 · NVIDIA/cccl

alliepiper · 2026-03-25T00:06:41Z

Summary

Closes #7053. Makes the documentation build fail on both Doxygen and Sphinx
warnings/errors, and fixes all existing issues so the build passes cleanly.

Sphinx (`-W` warnings-as-errors)

Add -W to SPHINXOPTS in gen_docs.bash
Fix all undefined RST label references, missing toctree entries, title
underline lengths, RST formatting errors, and duplicate labels
Add suppress_warnings in conf.py for cpp.duplicate_declaration and
docutils — breathe architecture limitations that cannot be fixed in source
Skip generating API pages for symbols with unparseable C++ declarations
(_BREATHE_SKIP_SYMBOLS in auto_api_generator.py)

Doxygen (`WARN_AS_ERROR = FAIL_ON_WARNINGS`)

Unify warning settings across all 4 Doxyfiles (cub, libcudacxx, thrust, cudax)
Fix gen_docs.bash to check Doxygen exit codes from parallel builds
Fix @param name mismatches across STF base classes, cudax launch, and CUB
Add _CCCL_DOXYGEN_INVOKED stubs for CUB namespace macros
Remove orphaned @endrst directives in CUB device headers
Fix @file tags, stale @param entries, and misused @name tags
Hide recursive template inheritance from Doxygen (graph_task, stream_task,
task_dep, CompileTimeArray)
Escape cross-project type references that Doxygen cannot resolve (each
project's Doxygen build is currently isolated from the others)
Hide _CCCL_DOXYGEN_INVOKED-guard ::cuda::std::execution::env defaults in
device_scan.cuh template signatures
Exclude CUB dispatch/ and kernels/ directories (internal implementation)
Remove duplicate tuple_element/tuple_size docs from thrust/pair.h
(authoritative docs remain in tuple.h)
Convert doc comments on excluded detail symbols to plain C++ comments
Restore __hierarchy to cudax Doxyfile INPUT (incorrectly removed)

Verification

Built docs from this branch and from the merge base with gen_docs.bash in
a devcontainer, then diffed the HTML output. All differences are accounted for:

29 CUB pages removed: Internal dispatch/kernel classes and enums now
excluded via EXCLUDE_PATTERNS. These were never public API.
4 symbol pages removed: get_executor_func_t, group,
has_property, property_with_value — skipped due to unparseable C++
declarations (breathe/Sphinx parser limitations on SFINAE expressions).
2 thrust pages moved: tuple_element/tuple_size moved from pair
group to tuple group (removed duplicate, kept authoritative location).
cudax hierarchy pages preserved: this_block, this_thread,
this_warp, this_grid, this_cluster all present after restoring
__hierarchy to INPUT.
No unexpected regressions in generated documentation content.

Test plan

docs/gen_docs.bash passes with zero Doxygen errors and zero Sphinx warnings
Diff of generated HTML against merge base shows no unexpected regressions

copy-pr-bot · 2026-03-25T00:06:46Z

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

alliepiper

/ok to test

alliepiper · 2026-03-25T00:32:14Z

/ok to test

alliepiper · 2026-03-25T00:54:16Z

/ok to test

miscco

I love this soo much

@param

Add missing @param tags, fix param name mismatches, remove stale params, and correct Doxyfile inputs across libcudacxx, cudax, CUB, and Thrust headers. Replace duplicate overload doc blocks in copy.h and fill.h with @overload. Fix minor doc formatting in CUB device headers and Python sort docstrings.

Add -W (warnings-as-errors) to SPHINXOPTS and quote paths in the sphinx build command. Replace toctree with ref links in auto-generated group pages to eliminate duplicate-toctree warnings. Fix undefined label references, add missing toctree entries for numeric overflow docs, fix RST formatting errors, and add stub anchors for in-progress container and graph features.

Skip generating API pages for 3 symbols whose Doxygen XML produces C++ declarations that breathe/Sphinx cannot parse (function-pointer typedefs, variable templates with SFINAE expressions). Suppress cpp.duplicate_declaration and docutils warning categories that arise from breathe architecture limitations. Remove container.rst stub anchors that collide with breathe-generated labels. Full doc build (Doxygen + Sphinx -W) now passes with zero warnings.

@param

Unify Doxygen warning settings across all 4 Doxyfiles with WARN_AS_ERROR=FAIL_ON_WARNINGS. Fix gen_docs.bash to check Doxygen exit codes from parallel builds. Add _CCCL_DOXYGEN_INVOKED stubs for CUB namespace macros. Remove orphaned @endrst directives, fix @param name mismatches across STF base classes and cudax launch overloads, fix @file tags, and clean up stale @param entries in CUB internals.

Add % prefix to ::cuda::std::tuple, ::cuda::std::execution::env, ::cuda::std::plus, ::std::tuple, and ::cuda::stream_ref in doc comments. The % tells Doxygen to render these as plain text instead of attempting to resolve them as cross-reference links.

Each CCCL project's Doxygen build is currently isolated, so types from other projects (e.g. cuda::std::tuple referenced from CUB) cannot be resolved. Drop :: global scope prefix from type names in doc comments and use monospace formatting instead. For template default arguments in C++ signatures, hide ::cuda::std::execution::env from Doxygen behind _CCCL_DOXYGEN_INVOKED guards.

@name

Change @name to @brief on shape_of copy constructor doc blocks. Doxygen's @name creates a member group, which caused @param tags from adjacent doc blocks to bleed into unrelated members like size() and get_capacity(). Also fix @param size0 to match the actual parameter name (sizes) in the coords_t constructor.

@relates

Remove stray @} with no matching @{ in buffer.h. Remove duplicate @relates in zip_function.h (Doxygen allows only one per block). Add missing @endrst to close an RST block in block_load_to_shared.cuh. Fix @snippet filename from unittest.h to unittest.cuh in traits.cuh and add EXAMPLE_PATH to cudax Doxyfile so Doxygen can find it.

Doxygen cannot handle self-referential template inheritance (CRTP and recursive specialization patterns). Hide the recursive base class from Doxygen with _CCCL_DOXYGEN_INVOKED guards on graph_task, stream_task, and task_dep. Hide the entire CompileTimeArray recursive template in WarpExchangeShfl since it is a private implementation detail.

Convert discard_temp_storage doc comments from Doxygen markup to plain C++ comments since the symbol is in a detail namespace excluded by EXCLUDE_SYMBOLS. Hide __ensure_current_context out-of-class definition and structured_binding_size specialization from Doxygen with _CCCL_DOXYGEN_INVOKED guards. Remove \var doc for batch_memop enum value that is commented out and not yet defined.

Both pair.h and tuple.h documented these symbols under different Doxygen @addtogroup groups, causing "Member documentation found several times in @addtogroup groups" errors. Remove the Doxygen aliases and doc comments from pair.h, keeping tuple.h as the single authoritative location (which includes deprecation notices and cross-references).

Add */dispatch/* and */kernels/* to CUB Doxyfile EXCLUDE_PATTERNS. These directories contain only internal dispatch machinery and kernel launch functions, not public API. Doxygen was erroring on symbols like vsmem_helper_t::discard_temp_storage because EXTRACT_ALL pulled them in but EXCLUDE_SYMBOLS excluded their underlying detail types.

The WIP merge incorrectly removed __hierarchy from the Doxygen input paths. This directory exists and contains public API classes including this_block, this_thread, this_warp, this_grid, and this_cluster.

The group concept uses _CCCL_REQUIRES_EXPR which expands to an expression that Sphinx's C++ parser cannot handle. Exposed by restoring __hierarchy to the cudax Doxyfile INPUT.

alliepiper · 2026-03-25T19:51:49Z

/ok to test

cub/cub/util_namespace.cuh

cub/cub/util_vsmem.cuh

docs/_ext/auto_api_generator.py

docs/cub/Doxyfile

docs/gen_docs.bash

libcudacxx/include/cuda/__stream/stream_ref.h

cudax/include/cuda/experimental/__stf/internal/data_interface.cuh

libcudacxx/include/cuda/__memory_resource/legacy_pinned_memory_resource.h

bernhardmgruber · 2026-03-25T21:37:24Z

cub/cub/device/device_scan.cuh

+            typename EnvT = // Doxygen cannot resolve ::cuda::std::execution::env
+#ifdef _CCCL_DOXYGEN_INVOKED
+            void
+#else
+            ::cuda::std::execution::env<>
+#endif


This is very sad! Is there a way we can properly fix this? Environment overloads will show up everywhere!

There is a fix we can consider as part of the env rollout. I've filed a bug to track.

#8176

tldr to save a click -- this fails because all of our projects use separate doxyfiles, and CUB's parser doesn't know about libcudacxx's symbols. Doxygen has some 'tagfile' mechanism to let the projects share cross-referencing info that would be great for a followup.

github-actions · 2026-03-26T01:52:05Z

🥳 CI Workflow Results

🟩 Finished in 1h 54m: Pass: 100%/425 | Total: 4d 23h | Max: 1h 37m | Hits: 97%/510549

See results here.

github-project-automation bot added this to CCCL Mar 25, 2026

github-project-automation bot moved this to Todo in CCCL Mar 25, 2026

cccl-authenticator-app bot moved this from Todo to In Progress in CCCL Mar 25, 2026

alliepiper commented Mar 25, 2026

View reviewed changes

alliepiper changed the title ~~Fix documentation build to pass with warnings-as-errors~~ Doc issues fail CI Mar 25, 2026

This comment has been minimized.

Sign in to view

miscco approved these changes Mar 25, 2026

View reviewed changes

alliepiper added 16 commits March 25, 2026 13:31

Revert working changes.

baa5d18

Fix precommit.

8e196e8

Add missing label anchor for uninitialized-async-buffer ref

f7faa18

Restore :: global scope prefix in block_radix_sort doc comments

d1ff367

alliepiper force-pushed the 7053_doc_ci_fail branch from a2f3b81 to 70162c4 Compare March 25, 2026 18:29

alliepiper added 3 commits March 25, 2026 15:01

Restore __hierarchy to cudax Doxyfile INPUT

a4da072

The WIP merge incorrectly removed __hierarchy from the Doxygen input paths. This directory exists and contains public API classes including this_block, this_thread, this_warp, this_grid, and this_cluster.

Add cuda::experimental::group to breathe skip list

e706400

The group concept uses _CCCL_REQUIRES_EXPR which expands to an expression that Sphinx's C++ parser cannot handle. Exposed by restoring __hierarchy to the cudax Doxyfile INPUT.

clang-format

4107fd7

alliepiper marked this pull request as ready for review March 25, 2026 20:03

alliepiper requested review from a team as code owners March 25, 2026 20:03

alliepiper requested review from elstehle, ericniebler, fbusato and kkraus14 March 25, 2026 20:03

cccl-authenticator-app bot moved this from In Progress to In Review in CCCL Mar 25, 2026

Jacobfaib reviewed Mar 25, 2026

View reviewed changes

alliepiper added 2 commits March 25, 2026 16:27

Suppress unused-parameter warnings on named allocator ctx params

7c9c184

Revert unnecessary util_vsmem.cuh doc comment change

373baae

caugonnet reviewed Mar 25, 2026

View reviewed changes

cudax/include/cuda/experimental/__stf/internal/data_interface.cuh Show resolved Hide resolved

caugonnet reviewed Mar 25, 2026

View reviewed changes

cudax/include/cuda/experimental/__stf/internal/data_interface.cuh Show resolved Hide resolved

bernhardmgruber reviewed Mar 25, 2026

View reviewed changes

alliepiper added 2 commits March 25, 2026 17:44

Add consistent logging to all _BREATHE_SKIP_SYMBOLS skip sites

d461d93

Revert unnecessary param naming on unused operator parameters

29883a1

pciolkosz approved these changes Mar 25, 2026

View reviewed changes

alliepiper mentioned this pull request Mar 25, 2026

[DOC]: Use doxygen tagfiles for better cross-project references #8176

Open

1 task

Auto-detect and install doc build dependencies in gen_docs.bash

ad31617

alliepiper requested a review from a team as a code owner March 25, 2026 22:38

bernhardmgruber approved these changes Mar 25, 2026

View reviewed changes

formatting.

c98b0bd

Conversation

alliepiper commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Sphinx (-W warnings-as-errors)

Doxygen (WARN_AS_ERROR = FAIL_ON_WARNINGS)

Verification

Test plan

Uh oh!

copy-pr-bot bot commented Mar 25, 2026

Uh oh!

alliepiper left a comment

Choose a reason for hiding this comment

Uh oh!

alliepiper commented Mar 25, 2026

Uh oh!

alliepiper commented Mar 25, 2026

Uh oh!

This comment has been minimized.

miscco left a comment

Choose a reason for hiding this comment

Uh oh!

alliepiper commented Mar 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bernhardmgruber Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

alliepiper Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

alliepiper Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 26, 2026

🥳 CI Workflow Results

🟩 Finished in 1h 54m: Pass: 100%/425 | Total: 4d 23h | Max: 1h 37m | Hits: 97%/510549

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

alliepiper commented Mar 25, 2026 •

edited

Loading

Sphinx (`-W` warnings-as-errors)

Doxygen (`WARN_AS_ERROR = FAIL_ON_WARNINGS`)