Use Sphinx and Breathe (+Doxygen) for documentation

[TheJJ]

Currently, we have Doxygen to generate our inline C++ documentation (libopenage/). We also use it for the Python code (openage/), but we should switch to Sphinx for this.

To beautify our doc/ folder, we could use Sphinx.

To link between both, there is Breathe.

For more automatization (file hierarchy, ...), we can use Exhale.

Then we would have a nice and one-for-all documentation by Sphinx: It natively support Python, the C++ parsing is still done by Doxygen which would be nicely integrated via breathe.

[simonsan]

The excellent doxypy makes it possible to embed Doxygen commands in Python docstrings, and have those docstrings converted to Doxygen-recognized comments on the fly per Doxygen's regular input filtering process. It however does not address any of the other previously mentioned areas of difficulty.

This project started off as a fork of doxypy but quickly became quite distinct. It shares little (if any) of the same code at this point (but maintains the original license just in case). It is meant to support all the same command line options as doxypy, but handle additional Python syntax beyond docstrings.

https://github.com/Feneric/doxypypy

I take a look, if it is possible to do the whole documentation thing in doxygen with doxypy/doxypypy. If it's is not really working out I'll stick to the Sphinx and Breathe approach. If anyone has other recommendations to easily generate documentation with less software dependencies please leave them here.

[TheJJ]

A simple implementation of this is for example https://gitlab.lrz.de/IP/elsa/-/tree/master/docs, the results are here: https://ciip.in.tum.de/elsadocs/

For it to work one needs doxygen, sphinx, sphinx_rtd_theme, breathe and m2r installed.