Documentation

[tedmiddleton]

Documentation! mainframe needs to some documentation. Something with doxygen and sphinx most likely

[tedmiddleton]

This has been a bit tricky. For one, doxygen itself is kind of unhelpful when it comes to writing documentation. I almost don't want doxygen to emit the whole function signature because the signatures are complicated and kind of confusing because they make use of complicated return types that do things like rearranging or mutating columns. If I could somehow have a transformer for the signatures or some way of adding a custom signature in addition to the actual signature, I think the docs would be much more useful.

Also, all of the tutorials for interfacing cmake+sphinx+doxygen to readthedocs seem to involve adding documentation generation as part of the ALL target, which I would rather not do because it interferes with development. I'd like documentation generation to exist exclusively inside the CI. I haven't looked very closely at how this integration works, though. I'll have to learn a bit more about this.

[tedmiddleton]

Sphinx is gone - and instead I'm using @jothepro's fantastic doxygen-awesome-css project which is great at un-uglifying doxygen output. And I'm serving the documentation at mainframe with github pages.

Now I just have to finish documenting everything!