cccl icon indicating copy to clipboard operation
cccl copied to clipboard

Comprehensive / single-page API reference

Open bdice opened this issue 3 years ago • 3 comments

Problem

The old Thrust documentation website at https://thrust.github.io/doc/namespacethrust.html has a single page containing a list of all Thrust APIs. This is extremely helpful as a "cheat sheet" for finding specific algorithms or overloads (via Ctrl+F) or simply referencing the breadth of the library's functionality. Similarly, the left sidebar of pages like this one for thrust::find shows a list of algorithms that is helpful for quick access.

The new Thrust documentation website at https://nvidia.github.io/thrust/ has categories like API / Algorithms / Reductions / Comparisons / thrust::equal but it seems to be missing a comparable list of algorithms for quick reference. It also seems that the number of clicks needed to navigate the new site's menu structure is higher, and it can be challenging to know which category contains a given API when searching for its docs. As a somewhat separate observation, the large amount of text on each page (and lower readability of the theme in both font size and contrast) makes it difficult to quickly compare the available overloads for a method.

Comparison to other algorithms libraries

Similar libraries like the C++ STL have reference pages like https://en.cppreference.com/w/cpp/numeric that list all algorithms in a given header, as well as a comprehensive list of headers / categories as shown in https://en.cppreference.com/w/cpp.

Proposed solution

Some mixture of tables of contents, all-in-one reference pages, or "cheat sheets" would be a highly valuable addition to the new Thrust documentation, especially if they can balance conciseness and readability with completeness as well as the old site did.

I would be happy to work on this at some point, but don't let that stop anyone else from jumping in if I haven't gotten to it yet!

cc: @karthikeyann @upsj @PointKernel who also showed interest in this kind of reference material.

bdice avatar Aug 19 '22 23:08 bdice

An important feature of the new docs (that I myself tend to forget) is the search-bar with suggestions which the old one was lacking. It should be an even better replacement for Ctrl-F on the overview page. Better overview pages would still be nice though.

pauleonix avatar Feb 13 '23 18:02 pauleonix

@bdice Just a small notice that all the links in the original problem description now point to the new docs since we are forwarding everything to the new docs now. Me though, that I've never seen the old docs, I got the gist just from the textual description.

gonidelis avatar Mar 14 '24 17:03 gonidelis

@gonidelis Please check this link https://web.archive.org/web/20230128153635/https://thrust.github.io/doc/namespacethrust.html since original ones are redirected now.

karthikeyann avatar Mar 14 '24 18:03 karthikeyann