Expert Python Programming - Third Edition

Module helper

The last template that can be added in our collection is the module helper template. A module helper refers to a single module and provides a description of its contents, together with usage examples.

Some tools can automatically build such documents by extracting the docstrings and computing module help using pydoc, such as Epydoc (refer to http://epydoc.sourceforge.net). So, it is possible to generate extensive documentation based on API introspection. This kind of documentation is often provided in Python frameworks. For instance, Plone provides a server that keeps an up-to-date collection of module helpers. You can read more about it at http://api.plone.org.

The following are the main problems with this approach:

• There ...