Flatten CUB/Thrust API docs

[bernhardmgruber]

This PR moves the CUB and Thrust API docs out of their sub directories, so they are less hidden more easily discovered. Furthermore, maintainer docs are added to the end. In the CUB docs, the "CUB" prefix of the headings is removed for consistency with other libraries.

• Merge before Small CUB doc corrections #10011

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 90ff957d-e05f-4076-b886-942cc977a364

📥 Commits

Reviewing files that changed from the base of the PR and between 703b096 and 23e32f8.

📒 Files selected for processing (64)

• docs/cub/api.rst
• docs/cub/benchmarking.rst
• docs/cub/block_wide.rst
• docs/cub/determinism.rst
• docs/cub/developer_overview.rst
• docs/cub/device_topk_requirements.rst
• docs/cub/device_wide.rst
• docs/cub/index.rst
• docs/cub/thread_level.rst
• docs/cub/tuning.rst
• docs/cub/tuning_infra.rst
• docs/cub/warp_wide.rst
• docs/thrust/algorithms.rst
• docs/thrust/algorithms/copying.rst
• docs/thrust/algorithms/copying/gather.rst
• docs/thrust/algorithms/copying/scatter.rst
• docs/thrust/algorithms/merging.rst
• docs/thrust/algorithms/prefix_sum.rst
• docs/thrust/algorithms/prefix_sums/segmented.rst
• docs/thrust/algorithms/prefix_sums/transformed.rst
• docs/thrust/algorithms/reductions.rst
• docs/thrust/algorithms/reductions/comparisons.rst
• docs/thrust/algorithms/reductions/counting.rst
• docs/thrust/algorithms/reductions/extrema.rst
• docs/thrust/algorithms/reductions/logical.rst
• docs/thrust/algorithms/reductions/predicates.rst
• docs/thrust/algorithms/reductions/transformed.rst
• docs/thrust/algorithms/reordering.rst
• docs/thrust/algorithms/reordering/partitioning.rst
• docs/thrust/algorithms/reordering/shuffling.rst
• docs/thrust/algorithms/reordering/stream_compaction.rst
• docs/thrust/algorithms/searching.rst
• docs/thrust/algorithms/searching/binary_search.rst
• docs/thrust/algorithms/set_operations.rst
• docs/thrust/algorithms/sorting.rst
• docs/thrust/algorithms/transformations.rst
• docs/thrust/algorithms/transformations/filling.rst
• docs/thrust/algorithms/transformations/modifying.rst
• docs/thrust/algorithms/transformations/replacing.rst
• docs/thrust/api.rst
• docs/thrust/containers.rst
• docs/thrust/function_objects.rst
• docs/thrust/function_objects/adaptors.rst
• docs/thrust/function_objects/placeholder.rst
• docs/thrust/function_objects/predefined.rst
• docs/thrust/index.rst
• docs/thrust/iterators.rst
• docs/thrust/memory_management.rst
• docs/thrust/memory_management/allocators.rst
• docs/thrust/memory_management/memory_resources.rst
• docs/thrust/numerics.rst
• docs/thrust/parallel_execution_policies.rst
• docs/thrust/random.rst
• docs/thrust/random/distributions.rst
• docs/thrust/random/engine.rst
• docs/thrust/random/engine_adaptors.rst
• docs/thrust/random/predefined.rst
• docs/thrust/system.rst
• docs/thrust/system/diagnostics.rst
• docs/thrust/system/systems.rst
• docs/thrust/utility.rst
• docs/thrust/utility/pair.rst
• docs/thrust/utility/tuple.rst
• docs/thrust/utility/type_traits.rst

💤 Files with no reviewable changes (2)

• docs/thrust/api.rst
• docs/cub/api.rst

🚧 Files skipped from review as they are similar to previous changes (56)

• docs/thrust/algorithms/reductions/extrema.rst
• docs/cub/thread_level.rst
• docs/thrust/system/diagnostics.rst
• docs/thrust/algorithms/transformations.rst
• docs/thrust/parallel_execution_policies.rst
• docs/thrust/algorithms/set_operations.rst
• docs/thrust/random.rst
• docs/thrust/algorithms/reordering/stream_compaction.rst
• docs/thrust/function_objects/adaptors.rst
• docs/thrust/algorithms/merging.rst
• docs/thrust/algorithms/reductions/logical.rst
• docs/thrust/function_objects/placeholder.rst
• docs/thrust/algorithms/transformations/filling.rst
• docs/thrust/numerics.rst
• docs/thrust/random/engine_adaptors.rst
• docs/thrust/utility/tuple.rst
• docs/thrust/algorithms/copying/gather.rst
• docs/thrust/algorithms/reductions.rst
• docs/thrust/algorithms/prefix_sums/transformed.rst
• docs/thrust/containers.rst
• docs/thrust/algorithms/copying.rst
• docs/thrust/utility.rst
• docs/cub/benchmarking.rst
• docs/thrust/algorithms/searching.rst
• docs/thrust/algorithms/reordering.rst
• docs/thrust/algorithms/reductions/transformed.rst
• docs/cub/developer_overview.rst
• docs/thrust/algorithms/prefix_sums/segmented.rst
• docs/thrust/random/predefined.rst
• docs/thrust/algorithms/transformations/replacing.rst
• docs/thrust/index.rst
• docs/thrust/iterators.rst
• docs/thrust/algorithms/reordering/shuffling.rst
• docs/cub/block_wide.rst
• docs/thrust/function_objects/predefined.rst
• docs/thrust/memory_management/memory_resources.rst
• docs/thrust/algorithms/reordering/partitioning.rst
• docs/thrust/algorithms/copying/scatter.rst
• docs/thrust/algorithms/reductions/counting.rst
• docs/thrust/memory_management/allocators.rst
• docs/thrust/random/engine.rst
• docs/thrust/system/systems.rst
• docs/thrust/algorithms/searching/binary_search.rst
• docs/thrust/algorithms/reductions/predicates.rst
• docs/thrust/algorithms/transformations/modifying.rst
• docs/cub/device_wide.rst
• docs/thrust/system.rst
• docs/cub/determinism.rst
• docs/thrust/algorithms/prefix_sum.rst
• docs/thrust/random/distributions.rst
• docs/cub/warp_wide.rst
• docs/thrust/utility/type_traits.rst
• docs/thrust/function_objects.rst
• docs/thrust/algorithms/reductions/comparisons.rst
• docs/thrust/algorithms.rst
• docs/cub/device_topk_requirements.rst

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Reorganized CUB and Thrust documentation navigation and module landing pages, including updates to how API reference sections are surfaced in the rendered index.
  • Removed obsolete API entry points so the CUB/Thrust navigation no longer lists missing or empty pages.
  • Added guidance on deterministic and ordered DeviceTopK/DeviceBatchedTopK behavior using execution requirements.
  • Introduced new Thrust landing pages for algorithms, reordering, random generators, system, utilities, and function objects, and corrected many API cross-reference/link paths across the documentation.

Walkthrough

Changes

The PR reorganizes CUB and Thrust documentation navigation, corrects generated API and example include paths, adds module landing pages, and documents CUB top-k execution requirements.

CUB documentation

Layer / File(s)	Summary
Top-k requirements guide docs/cub/device_topk_requirements.rst	Documents determinism, tie-breaking, output ordering, supported configurations, examples, and configuration guidance for CUB top-k algorithms.
Navigation and content updates docs/cub/index.rst, docs/cub/*_wide.rst, docs/cub/thread_level.rst, docs/cub/benchmarking.rst, docs/cub/determinism.rst, docs/cub/developer_overview.rst, docs/cub/tuning*.rst	Updates CUB navigation, API paths, example includes, and page headings.

Thrust documentation

Layer / File(s)	Summary
Module landing pages docs/thrust/index.rst, docs/thrust/algorithms.rst, docs/thrust/algorithms/reordering.rst, docs/thrust/function_objects*, docs/thrust/random.rst, docs/thrust/system.rst, docs/thrust/utility.rst, docs/thrust/containers.rst	Adds or reorganizes Thrust module pages and documents function objects, random generators, system topics, utilities, and algorithm categories.
Algorithm API references docs/thrust/algorithms/**/*.rst	Adjusts generated API toctree paths across Thrust algorithm documentation.
Other API references docs/thrust/{iterators,memory_management,numerics,parallel_execution_policies,random,system,utility}.rst, docs/thrust/{function_objects,memory_management,random,system,utility}/*.rst	Updates generated API paths for non-algorithm Thrust documentation.

Possibly related PRs

• NVIDIA/cccl#10013 — Overlaps the CUB documentation entrypoint and navigation changes.

Suggested reviewers: ericniebler

---

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

[coderabbitai]

Actionable comments posted: 5

🧹 Nitpick comments (1)

docs/thrust/function_objects/predefined.rst (1)

3-4: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

suggestion: Rename the child page heading to “Predefined Function Objects”.

This page is already linked from the parent “Function Objects” page; a distinct heading will make navigation and generated page titles unambiguous.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 5954748b-81cc-4142-af80-3ad018021ee6

📥 Commits

Reviewing files that changed from the base of the PR and between 27e236a and 703b096.

📒 Files selected for processing (64)

• docs/cub/api.rst
• docs/cub/benchmarking.rst
• docs/cub/block_wide.rst
• docs/cub/determinism.rst
• docs/cub/developer_overview.rst
• docs/cub/device_topk_requirements.rst
• docs/cub/device_wide.rst
• docs/cub/index.rst
• docs/cub/thread_level.rst
• docs/cub/tuning.rst
• docs/cub/tuning_infra.rst
• docs/cub/warp_wide.rst
• docs/thrust/algorithms.rst
• docs/thrust/algorithms/copying.rst
• docs/thrust/algorithms/copying/gather.rst
• docs/thrust/algorithms/copying/scatter.rst
• docs/thrust/algorithms/merging.rst
• docs/thrust/algorithms/prefix_sum.rst
• docs/thrust/algorithms/prefix_sums/segmented.rst
• docs/thrust/algorithms/prefix_sums/transformed.rst
• docs/thrust/algorithms/reductions.rst
• docs/thrust/algorithms/reductions/comparisons.rst
• docs/thrust/algorithms/reductions/counting.rst
• docs/thrust/algorithms/reductions/extrema.rst
• docs/thrust/algorithms/reductions/logical.rst
• docs/thrust/algorithms/reductions/predicates.rst
• docs/thrust/algorithms/reductions/transformed.rst
• docs/thrust/algorithms/reordering.rst
• docs/thrust/algorithms/reordering/partitioning.rst
• docs/thrust/algorithms/reordering/shuffling.rst
• docs/thrust/algorithms/reordering/stream_compaction.rst
• docs/thrust/algorithms/searching.rst
• docs/thrust/algorithms/searching/binary_search.rst
• docs/thrust/algorithms/set_operations.rst
• docs/thrust/algorithms/sorting.rst
• docs/thrust/algorithms/transformations.rst
• docs/thrust/algorithms/transformations/filling.rst
• docs/thrust/algorithms/transformations/modifying.rst
• docs/thrust/algorithms/transformations/replacing.rst
• docs/thrust/api.rst
• docs/thrust/containers.rst
• docs/thrust/function_objects.rst
• docs/thrust/function_objects/adaptors.rst
• docs/thrust/function_objects/placeholder.rst
• docs/thrust/function_objects/predefined.rst
• docs/thrust/index.rst
• docs/thrust/iterators.rst
• docs/thrust/memory_management.rst
• docs/thrust/memory_management/allocators.rst
• docs/thrust/memory_management/memory_resources.rst
• docs/thrust/numerics.rst
• docs/thrust/parallel_execution_policies.rst
• docs/thrust/random.rst
• docs/thrust/random/distributions.rst
• docs/thrust/random/engine.rst
• docs/thrust/random/engine_adaptors.rst
• docs/thrust/random/predefined.rst
• docs/thrust/system.rst
• docs/thrust/system/diagnostics.rst
• docs/thrust/system/systems.rst
• docs/thrust/utility.rst
• docs/thrust/utility/pair.rst
• docs/thrust/utility/tuple.rst
• docs/thrust/utility/type_traits.rst

💤 Files with no reviewable changes (2)

• docs/cub/api.rst
• docs/thrust/api.rst

[coderabbitai]

Caution

Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.

Actionable comments posted: 5

🧹 Nitpick comments (1)

docs/thrust/function_objects/predefined.rst (1)

3-4: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

suggestion: Rename the child page heading to “Predefined Function Objects”.

This page is already linked from the parent “Function Objects” page; a distinct heading will make navigation and generated page titles unambiguous.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 5954748b-81cc-4142-af80-3ad018021ee6

📥 Commits

Reviewing files that changed from the base of the PR and between 27e236a and 703b096.

📒 Files selected for processing (64)

• docs/cub/api.rst
• docs/cub/benchmarking.rst
• docs/cub/block_wide.rst
• docs/cub/determinism.rst
• docs/cub/developer_overview.rst
• docs/cub/device_topk_requirements.rst
• docs/cub/device_wide.rst
• docs/cub/index.rst
• docs/cub/thread_level.rst
• docs/cub/tuning.rst
• docs/cub/tuning_infra.rst
• docs/cub/warp_wide.rst
• docs/thrust/algorithms.rst
• docs/thrust/algorithms/copying.rst
• docs/thrust/algorithms/copying/gather.rst
• docs/thrust/algorithms/copying/scatter.rst
• docs/thrust/algorithms/merging.rst
• docs/thrust/algorithms/prefix_sum.rst
• docs/thrust/algorithms/prefix_sums/segmented.rst
• docs/thrust/algorithms/prefix_sums/transformed.rst
• docs/thrust/algorithms/reductions.rst
• docs/thrust/algorithms/reductions/comparisons.rst
• docs/thrust/algorithms/reductions/counting.rst
• docs/thrust/algorithms/reductions/extrema.rst
• docs/thrust/algorithms/reductions/logical.rst
• docs/thrust/algorithms/reductions/predicates.rst
• docs/thrust/algorithms/reductions/transformed.rst
• docs/thrust/algorithms/reordering.rst
• docs/thrust/algorithms/reordering/partitioning.rst
• docs/thrust/algorithms/reordering/shuffling.rst
• docs/thrust/algorithms/reordering/stream_compaction.rst
• docs/thrust/algorithms/searching.rst
• docs/thrust/algorithms/searching/binary_search.rst
• docs/thrust/algorithms/set_operations.rst
• docs/thrust/algorithms/sorting.rst
• docs/thrust/algorithms/transformations.rst
• docs/thrust/algorithms/transformations/filling.rst
• docs/thrust/algorithms/transformations/modifying.rst
• docs/thrust/algorithms/transformations/replacing.rst
• docs/thrust/api.rst
• docs/thrust/containers.rst
• docs/thrust/function_objects.rst
• docs/thrust/function_objects/adaptors.rst
• docs/thrust/function_objects/placeholder.rst
• docs/thrust/function_objects/predefined.rst
• docs/thrust/index.rst
• docs/thrust/iterators.rst
• docs/thrust/memory_management.rst
• docs/thrust/memory_management/allocators.rst
• docs/thrust/memory_management/memory_resources.rst
• docs/thrust/numerics.rst
• docs/thrust/parallel_execution_policies.rst
• docs/thrust/random.rst
• docs/thrust/random/distributions.rst
• docs/thrust/random/engine.rst
• docs/thrust/random/engine_adaptors.rst
• docs/thrust/random/predefined.rst
• docs/thrust/system.rst
• docs/thrust/system/diagnostics.rst
• docs/thrust/system/systems.rst
• docs/thrust/utility.rst
• docs/thrust/utility/pair.rst
• docs/thrust/utility/tuple.rst
• docs/thrust/utility/type_traits.rst

💤 Files with no reviewable changes (2)

• docs/cub/api.rst
• docs/thrust/api.rst

🛑 Comments failed to post (5)

docs/cub/device_topk_requirements.rst (2)

45-75: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

important: Clearly mark the deterministic, sorted, and default configurations as future contract rather than currently usable. The supplied DeviceTopK and DeviceBatchedTopK implementations reject these combinations, including the empty environment, yet this page presents them as runnable defaults and recommendations. As per path instructions, documentation changes must be checked for technical accuracy and buildable examples.

Also applies to: 147-160, 202-210, 304-323

Source: Path instructions

---

222-225: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

important: Correct the worked-example count: indices 1, 2, and 3 contain three tied 8 values, not four. Only two of those three can be selected for K = 3.

Source: Path instructions

docs/cub/index.rst (1)

486-486: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

important: Fix the malformed reStructuredText hyperlink. Use an inline link such as See also \CCCL LICENSE https://github.com/NVIDIA/cccl/blob/main/LICENSE`_` so the link is rendered and checked by Sphinx. As per path instructions, documentation changes must be checked for technical accuracy and buildability.

Source: Path instructions

docs/thrust/function_objects.rst (1)

53-56: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

critical: Use the binary transform overload in this example.

The lambda takes two arguments, but this call supplies only one input range, so the example does not compile. Add b.begin() as the second input range.

-    thrust::transform(thrust::device, a.begin(), a.end(), a.begin(),
+    thrust::transform(thrust::device, a.begin(), a.end(), b.begin(), a.begin(),

As per path instructions, documentation examples must remain buildable.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

    thrust::transform(thrust::device, a.begin(), a.end(), b.begin(), a.begin(),
        cuda::std::proclaim_copyable_arguments([](const int& a, const int& b) {
            return a + b;
        }));

Source: Path instructions

docs/thrust/function_objects/adaptors.rst (1)

6-6: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

important: Remove the leading indentation from these top-level bullet lists.

The bullets are outside a directive, so the two-space indentation can make them render as an indented block instead of a normal list.

• docs/thrust/function_objects/adaptors.rst#L6-L6: change - to -.
• docs/thrust/function_objects/predefined.rst#L9-L11: remove the two leading spaces from each bullet.

📍 Affects 2 files

• docs/thrust/function_objects/adaptors.rst#L6-L6 (this comment)
• docs/thrust/function_objects/predefined.rst#L9-L11

Source: Path instructions

[bernhardmgruber]

Most important change. Put the algorithms out of API documentation onto the first level and at the top.

[davebayer]

LGTM