Add _graph_ to our API reference documentation

[cchriste]

Currently we have Doxygen set up, but not the graphs since they take hours to generate.
The API displayed in other projects such as pybind11 seems very nice, so may be worthwhile to look at what they use.

Our API is documented, but doesn't include the graph of classes, etc, since that takes a long time to generate. This time may be unavoidable, so perhaps we can resolve this by adding a boolean to our GitHub action that optionally generates the graph and only use it for the final release docs.

[sheryjoe]

@medakk this is the issue related to pybind11 documentation. Please let us know what you find.

[medakk]

Looks like sphinx is recommended for this purpose.

[sheryjoe]

We could still use mkdocs for our user documentation and sphinx for API docs.
https://pypi.org/project/mkinx/

[akenmorris]

Just FYI, sphinx doesn't really do C++. Seems you use doxygen either way.

https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/

"Sphinx doesn’t have the ability to extract API documentation from C++ headers; this needs to be supplied either by hand or from some external tool. We can use Doxygen to do this job for us. "

https://stackoverflow.com/questions/12933900/is-sphinx-already-suitable-for-c-documentation

"Sphinx cannot extract documentation from C++ sources in and by itself. However, there are extensions, most notably Breathe, which utilize Doxygen to extract documentation from C++. I've not tested any of these."

[akenmorris]

Also, it's only the dependency graph stuff (using dot/graphviz) that take long to generate. I think the 7-8 level inheritance trees with templates are the root cause. It you disable the graph gen, it doesn't take all that long.

[cchriste]

This would be especially useful for people trying to use our Python API, similar to what we currently have for our command line (I hope this is auto-generated since if not it's out of date).

[cchriste]

Here are the available plugins for mkdocs: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#api-documentation-building
Doxygen is my recommendation since we already use it, it handles c++, and the plugin will magically add what we need.