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

[gonidelis]

Is this a duplicate?

• I confirmed there appear to be no duplicate issues for this bug and that I agree to the Code of Conduct

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<int ITEMS_PER_THREAD, typename T> 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.

• Split Warp-Wide Primitives into Reference and Explanation pages  #2893
• Split Block-Wide Primitives into Reference and Explanation pages  #2894
• Split Device-Wide Primitives into Reference and Explanation pages  #2895