How to document python code

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):

• epydoc
• sphinx 
• doxygen

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

	def myfunc(message):
	"""
	This is external function
	@param message: this is string that is going to be printed
	@return: none
	"""
	print("myfunc: %s" % message)
	class MyClass:
	"""
	My class that implement 2 demo functions.
	"""
	def __init__(self, s):
	self.s=s
	def f1(self, message=None):
	"""
	The function prints a string on stdout
	@param message: a string
	"""
	print("main:f1: %s" % message)
	def f2(self, message=None):
	"""
	The function prints a string on stdout
	@param message: a string
	@return: a value zero
	"""
	print("main:f2: %s" % message)
	return 0
	def main(self):
	self.f1(self.s)
	self.f2(self.s)
	myfunc(self.s)
	if __name__ == '__main__':
	MyClass('epydoc demo').main()

view raw example_epydoc.py hosted with ❤ by GitHub

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

1. http://stackoverflow.com/questions/4126421/how-to-document-python-code-epydoc-doxygen-sphinx
2. http://stackoverflow.com/questions/1125970/python-documentation-generator
3. http://stackoverflow.com/questions/5334531/python-documentation-standard-for-docstring
4. http://epydoc.sourceforge.net/
5. http://sphinx-doc.org/