NVIDIA / NVIDIA/cccl

[DOC]: Split CUB primitives pages into Reference and Explanation pages [diataxis]

Open
#2,892 0 comments 0 reactions 1 assignee Claimed by @gonidelis View on GitHub
Dominant language
C++
Stars
2.5k
Forks
486
Avg merge
2d 6h
Merged PRs (30d)
295

Description

### Is this a duplicate?

- [x] I confirmed there appear to be no [duplicate issues](https://github.com/NVIDIA/cccl/issues) for this bug and that I agree to the [Code of Conduct](CODE_OF_CONDUCT.md)

### Is this for new documentation, or an update to existing docs?

New

### Describe the incorrect/future/missing documentation

The pages for CUB primitives (Warp, Block, Device) are cluttered:

* All the APIs for a single Primitive are under a single page (this doesn't align with our Thrust APIs). We should follow either or. IMO we should conform to Thrust given that some APIs provide bulk information that might be lost if not in a distinct page. This also helps in the remark below.
* We provide a generic "A Simple Example" at the top of the primitive which uses **just one** of the algorithms provided by the primitive. Then under the API reference for each algorithm we attach along a "Snippet" which showcases its usage.
1. The latter we should keep as the generic/minimal code example along with each API reference.
2. The former ("Simple Example") along with "Supported Types", "Performance Considerations", "Reusing dynamically allocating shared memory" etc. should be abstracted away to a top (or parallel) Explanation page.

Here's a schematic. Each endpoint is a distinct HTML page.

# CUB Docs

## Device Wide primitives

### cub::DeviceReduce

- Usage and Performance
- API
- Reduce
- Sum
- Min
- ArgMin
- Max
- ArgMax

### cub::DeviceFor
- Usage and Performance
- API
- Bulk
- ForEachN
- ForEach

## Block Wide primitives

### cub::BlockReduce
- Usage and Performance (if bulky then split again)
- API
- template T Reduce(T input, ReductionOp reduction_op)
- template T Reduce(T (&inputs)[ITEMS_PER_THREAD], ReductionOp reduction_op)
- template T Reduce(T input, ReductionOp reduction_op, int num_valid)

How to express and distinct algorithms with the same name and different signature in the drop down tree is a problem that will be discusses in a different issue.

---
Each of the following tasks/issues is split into each own sub-tasks.

- [ ] #2893
- [ ] #2894
- [ ] #2895

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.