Consistent internal documentation style/format.

[woodruffw]

We should settle on a documentation style and format so that we can generate searchable documentation.

Options: Doxygen, Sphinx-doc, cldoc, NaturalDocs

[haxmeadroom]

Is there a summary of the differences between these laying around anywhere?

[woodruffw]

There are probably a few blog posts comparing individual pairs, although I don't know of anything that formal. Let me see if I can find some.

Personally, I've used Doxygen and found it decent for most C/C++ codebases.

[woodruffw]

Looks like Sphinx is relatively popular for Python codebases, while Doxygen supports Python nominally (but not idiomatically, it can't do generation within docstrings).

cldoc is clang based so probably not that useful for us. NaturalDocs looks pretty nice to use, but it's also a big pile of Perl and so probably an unnecessary hassle to get set up.

Edit: NaturalDocs also lists its Python support as "basic": https://www.naturaldocs.org/reference/language_support/#languages. Probably not ideal for our purposes.

[ehennenfent]

Relevant for Doxygen: https://pypi.org/project/doxypypy/

[haxmeadroom]

I've been going with doxygen for the python stuff recently. Haven't tested it out to see what it looks like but hopefully it's ok.

[haxmeadroom]

Starting generating doxygen to doc/html/index.html

[ehennenfent]

@haxmeadroom When you get a chance, can you strip the rendered docs from the git commit history? We'll be expanding the source comments a lot in the next couple weeks and I'd rather keep the doxyfile and individually rebuild on our respective machines than pass around thousands of lines of rendered docs.

[haxmeadroom]

Sure.. Yeah, it was getting annoying for me too . added ./make doc if you have doxygen installled to build them

[ehennenfent]

Most comments have been converted to doxygen format.