code documentation for python

Question

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

Answer 1

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

Tools for generating documentation: for example Sphinx

Answer 2

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

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

Answer 3

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.

Answer 4

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.