[JOSS Pre-Review]: Using Doxygen as opposed to hard-coded .rst

[villaa]

There is an outline of the API now too (another great improvement). It is hardcoded in the docs .rst files though, which is not great as this is extremely brittle and prone to drift. What would be quite a bit nicer would be to generate the docs from the source code itself (for C++ code the obvious method is Doxygen and there are tutorials and examples out there on how to build Doxygen annotated projects in Sphinx.)

The API documentation section of the review guidelines mentions

the software API is documented to a suitable level.

So while as a library maintainer I can strongly recommend that this be done, it isn't a requirement for the review — but it would certainly improve the usefulness of the API docs.

[villaa]

Doxygen isn't really made to work natively with Sphinx although it seems to have been done through the use of Breathe. Not sure if CMake is required, although it is used in that example.

[villaa]

Or maybe try this example or this one..

[villaa]

Here is the syntax of Breathe the bridge from doxygen to Sphinx/RestructuredText.

[villaa]

addressed by PR #68