code documentation for python

Question

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

score 38 · Answer 1 · answered Mar 11 '09 at 16:56

38

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

Tools for generating documentation: for example Sphinx

answered Mar 11 '09 at 16:56

vartec

131,205
36
218
244

This should be the accepted answer – shrewmouse Jan 10 '19 at 15:24
Or, if you find yourself averse to reStructuredText, [pdoc](https://pdoc3.github.io/pdoc) also supports markdown and numpydoc docstring formats. – K3---rnc Jan 10 '19 at 16:48

score 16 · Answer 2 · answered Mar 11 '09 at 17:08

16

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.

answered Mar 11 '09 at 17:08

S.Lott

384,516
81
508
779

score 10 · Accepted Answer · answered Mar 11 '09 at 17:06

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.

score 6 · Answer 4 · answered Mar 11 '09 at 17:00

6

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

answered Mar 11 '09 at 17:00

dwc

24,196
7
44
55

score 1 · Answer 5 · answered Mar 07 '14 at 10:20

1

using doxypy filter with doxygen is a good thing also

answered Mar 07 '14 at 10:20

sancelot

1,905
12
31

code documentation for python

5 Answers5