Migrating from Javadoc to Python Documentation

Question

So I've gotten somewhat used to Javadoc style documentation. Looking through various examples of Python code, I'm finding that, at first blush, the documentation seems to be missing a lot of information.

The good: vary rarely do you see self-evident bits of documentation. Docstrings are usually a paragraph or less of English markup that integrates instead of standing out on separate lines.

The bad: in conjunction with Python's duck-typing, I find that many functions are unclear about the parameters they expect. There's no type hinting (duck-hinting?) and often times it would be nice to have some idea that the parameter should be list-like, string-like, stream-like.

Of course, Javadoc was designed for a lower-level language, without great introspection abilities of Python, which might account for the less verbose documentation philosophy.

Any advice on Python documentation standards and best-practices?

Answer 1

The reStructuredText format was designed in response to the need for Python documentation that could be embedded in docstrings, so the best thing is to learn reST and format your docstrings with that format. You might find, as I did, that you then go on to format just about any documentation in reST, but that's a side point :-)

For specifically documenting your Python code, the Sphinx system is a set of extensions to the reST format, and a build system for rendering documents. Since it was designed to document Python itself, including the standard library, Sphinx allows for very well-structured documentation of source code, including of course the specifics of function signatures as you're asking. It allows a comprehensive documentation suite to be built, both auto-extracted and hand-written, all using the same formatting system.

If you only want documentation generated from your source code, then Epydoc will extract API documentation from your source code; it, too, reads reST formatting for the text.