Prev Next | Back Along | Up Home

4.1   Can I use Docutils for Python auto-documentation?

Yes, in conjunction with other projects.

Docstring extraction functionality from within Docutils is still under development. There is most of a source code parsing module in docutils/readers/python/moduleparser.py. I (David Goodger) haven't worked on it in a while, but I do plan to finish it eventually. Ian Bicking wrote an initial front end for my moduleparser module, in sandbox/ianb/extractor/extractor.py. There has also been some recent activity in sandbox/tibs/pysource2/.

Version 2.0 of Ed Loper's Epydoc supports reStructuredText-format docstrings for HTML output. Docutils 0.3 or newer is required. Development of a Docutils-specific auto-documentation tool will continue. Epydoc works by importing Python modules to be documented, whereas the Docutils-specific tool, described above, will parse modules without importing them (as with HappyDoc, which doesn't support reStructuredText).

The advantages of parsing over importing are security and flexibility; the disadvantage is complexity/difficulty.

For more details, please see "Docstring Extraction Rules" in PEP 258, item 3 ("How").

Prev Next | Back Along | Up Home