There are couple of way how you can document a python code. In this article I'm not trying to compare them but rather to show how a final documentation may look like.
Problem
How many tools can we use to generate documentation from python source.
How a final documentation look like after generation from a source code.
Analysis
When searching on Google we quickly find that the most popular are (there are more that I'm not listing here):
Example
These are examples how the documentation looks like.
Epydoc - It has as stile of a classical javadoc documentation introduced by Sun when Java was released.
Sphinx - the layout is very different from Epydoc. It seems to be very likable by the python project itself. All the doc for it is generated using it.
Demonstration
Epydoc installation
# python --version
Python 2.7.3
# aptitude show python-epydoc
# aptitude install python-epydoc
# aptitude install apache2
The source code
Generation of epydoc documentation
# epydoc --verbose --verbose example_epydoc.py
Building documentation
[ 0%] example_epydoc (example_epydoc.py)
Merging parsed & introspected information
[ 0%] example_epydoc
Linking imported variables
[ 0%] example_epydoc
[ 12%] example_epydoc.MyClass
Indexing documentation
[ 0%] example_epydoc
Checking for overridden methods
[ 12%] example_epydoc.MyClass
Parsing docstrings
[ 0%] example_epydoc
[ 12%] example_epydoc.MyClass
Inheriting documentation
[ 12%] example_epydoc.MyClass
Sorting & Grouping
[ 0%] example_epydoc
[ 12%] example_epydoc.MyClass
Writing HTML docs to 'html'
[ 4%] epydoc.css
[ 9%] epydoc.js
[ 13%] identifier-index.html
[ 45%] module-tree.html
[ 50%] class-tree.html
[ 54%] help.html
[ 59%] frames.html
[ 63%] toc.html
[ 68%] toc-everything.html
[ 72%] toc-example_epydoc-module.html
[ 77%] example_epydoc-module.html
[ 81%] example_epydoc.MyClass-class.html
[ 86%] example_epydoc-pysrc.html
[ 90%] redirect.html
[ 95%] api-objects.txt
[100%] index.html
Timing summary:
Building documentation............. 0.2s |=================================================
Merging parsed & introspected i.... 0.0s |
Linking imported variables......... 0.0s |
Indexing documentation............. 0.0s |
Checking for overridden methods.... 0.0s |
Parsing docstrings................. 0.0s |=
Inheriting documentation........... 0.0s |
Sorting & Grouping................. 0.0s |
Writing HTML docs to 'html'........ 0.0s |=======
Showing the doc
You have to configure the Apache and points it to the generated 'html' directory. Once the page is loaded in the browser the documentation looks like this:
References
- http://stackoverflow.com/questions/4126421/how-to-document-python-code-epydoc-doxygen-sphinx
- http://stackoverflow.com/questions/1125970/python-documentation-generator
- http://stackoverflow.com/questions/5334531/python-documentation-standard-for-docstring
- http://epydoc.sourceforge.net/
- http://sphinx-doc.org/