Documentation

[bplimley]

Via Sphinx?

[bplimley]

Some relevant StackOverflow threads:

• How to document Python code?
• Can I document Python code with doxygen (and does it make sense)?

Some clarification if you're new to these doc tools:

• Doxygen automatically generates documentation from your source code, linking classes, functions, etc. However it is primarily designed for C++ and Java and for Python apparently you need doxypy or doxypypy to get it to recognize Python docstrings properly.
• Sphinx is what is used for the official Python docs. It's prettier than doxygen. Basic Sphinx requires you to write the documentation but with hyperlinks to your code. But there's an autodoc extension that automatically builds documentation from your code, similar to doxygen. Sphinx is built specifically for Python. Mark's "Open sourcing a Python project the right way" link recommends Sphinx.

Regardless of which tool we use, we probably need to reformat our docstrings to make optimal use of the formatting and linking capabilities of the tool.