Docs update: how to use dynamic shared mem with block reduce

[MatthiasKohl]

As mentioned in #344, I created this PR to add a simple example of how to correctly use dynamic shared memory with BlockReduce.

I hope I followed the PR process correctly, I wasn't able to re-build the docs because the full build (for thrust) took longer than my allocated time on the machine when I was working on this, and I'm not familiar enough with the build process s.t. I can simply only build the docs for cub.
I'll amend the pull request, of course, if needed.

Plus, do you want me to add a similar example to classes like BlockScan ? In this case, it may be better to add an actual example file and link to it from the various inline docs.

[alliepiper]

I wasn't able to re-build the docs

No problem, our docs framework is a work-in-progress. This should improve soon.

it may be better to add an actual example file and link to it from the various inline docs.

I agree, this would be better to have a complete example under the examples/ directory. We'll build it as part of our CI to make sure it keeps working this way, too. Can you add this?

[MatthiasKohl]

I agree, this would be better to have a complete example under the examples/ directory. We'll build it as part of our CI to make sure it keeps working this way, too. Can you add this?

Sure, I'll add it as soon as I get some time for it (probably tomorrow).

[MatthiasKohl]

Sorry for the delay, but I finally got to doing this and added the full example.
I can see that the example compiles (and tests pass), but I'm not sure what the best way to integrate it into the docs is, yet.
Especially since I wasn't able to compile the docs.
Would it be possible for you to check that? It may also make sense to link to this example from other block-wide operations since they'll work basically the same w.r.t. shared memory

[alliepiper]

Unfortunately, our docs build is broken at the moment, so we can't really test this out just yet. NVIDIA/thrust#1475 is working on restoring it.

It might be best to just mention the name of the example without a link. Doxygen provides the \ref command to create internal links, but I don't see how to get that to link to a complete source file, it appears to only work with documentation blocks.

It may also make sense to link to this example from other block-wide operations since they'll work basically the same w.r.t. shared memory

Agreed -- could you update this PR to do so?

[MatthiasKohl]

Yes, I slightly reformulated the docs such that it should be clear where to find the example in case the tags don't work.
Although I believe they should work with doxygen and I've seen other projects using them (they are even supposed to be automatically substituted with references if you build the docs to LaTeX, but I'll believe it when I see it...).

And I added this example along with the short description to all block-wide operations except for BlockAdjacentDifference which doesn't seem to have any docs for now, and BlockShuffle which has very minimal docs.

[alliepiper]

@senior-zero is currently working on BlockAdjacentDifference -- George, can you include similar wording as the new docs here?

I should be able to get this merged in the next few days.

[alliepiper]

Made some minor modifications. Started tests in NVIDIA/thrust#1504.