Description
Context
As discussed by my closed issue Help needed with including example program snippets in the documentation, me (Sander) and Saiyang at StreamHPC are planning to replace the ~200 pseudocode examples that rocPRIM's algorithms have, like rocprim::search() here:
with example snippets that are compiled and tested by our CI:
The excess level of indentation is caused by a Doxygen bug, so the plan is to update rocPRIM's old 1.9.4 Doxygen version to the latest version of 1.13.2. But since the excess indentation isn't too awful looking, updating Doxygen can be done later down the line.
Changes that we'll be making
The pseudocode examples are at the moment all hardcoded as C++ comments, as seen in device_search.hpp.
We'll be including snippets of tested examples in the docs by putting //! [example] markers at the start and end of main(), and then using /// \snippet{trimleft} example_device_search.cpp example in device_search.hpp.
When we need to merge multiple snippets into a single block in the docs, we can instead use \dontinclude+\skipline+\until, as Albert suggested to me on Stack Overflow here.
Questions
Feel free to not address any of these questions that you don't have an answer for:
- Assuming we get the docs to build without any warnings, with the latest version version of Doxygen, and the website visually looks roughly the same, is there anything else we need to update or take into account?
- Is there any stylistic feedback (apart from the extra level of indentation looking bad)?
- I'm relatively new here, so I was wondering what StreamHPC's relation to the rocm-docs-core team is exactly. For instance, I'm not sure if this issue that notifies the rocm-docs-core team of this plan is expected of us, since StreamHPC is responsible for maintaining rocPRIM.
- We'd like to be able to test the link to the full example locally somehow, since the examples usually won't be available on rocPRIM's GitHub yet. For now we're going to cross our fingers that the links will always work. Any thoughts on this?