code documentation for python

Question

What is out there on conventions and tools for documenting python source code?

Solution 1

Epydoc is also a good tool for documenting source code, and handles cross-referencing classes, modules, variables, etc, into HTML, PDF, LaTeX. Draws some nice class inheritance diagrams too. It's used by a number of open-source projects, so it's fairly actively developed.

Solution 2

Conventions: PEP 257 and PEP 8. Note, that docstrings can be written in reStructuredText

Tools for generating documentation: for example Sphinx

Solution 3

First, put comments in your docstrings using RestructuredText format.

Second, get sphinx.

Third, create an index that uses the autodoc extension.

Then, run Sphinx to get really nice documentation.

Solution 4

It's very nice to put code documentation in the code itself. See:

• PEP 257 -- Docstring Conventions
• PEP 8 -- Style Guide for Python Code

Solution 5

using doxypy filter with doxygen is a good thing also

View more solutions

Comments

[shrewmouse]

This should be the accepted answer

[K3---rnc]

Or, if you find yourself averse to reStructuredText, pdoc also supports markdown and numpydoc docstring formats.