How To Generate Javadoc Style Documentation For Python

I’m a pure Java developer turned to a 50/50 Java/Python developer. Although I was skeptical about Python initially, but I’ve learned to love the language. Once you stop trying to program like Java in Python, it becomes much easier to see the Pythonic way. However, I do miss the explicitness of Java but have found that good documentation can make up for it to a good extent.

Given that in Python one does no explicitly declare the types of variable and function parameters, having a javadoc style documentation becomes even more important to make it explicit to the user the types that are expected by your code. Python also has the ability to declare optional functional parameters with default values. This indeed is a very powerful feature of the language. However, if you use it, documenting those optional parameters and their default values becomes very important as well.

Python docstrings provide the perfect mechanism for writing documentation around your modules, functions and parameters. Unlike Java, you can even access these docstrings programatically using the __doc__ attribute on an object. I thought this was pretty cool! However, I needed a tool, which could take these docstrings and generate html based documentation similar to how Javadoc works for Java.

This led me to the quest of finding an easy documentation generation tool for Python. I started my quest with looking into how Python’s own documentation is created. Soon enough, I was looking at Sphinx. I was really impressed with the powerful tools it had and the quality of the generated documentation. It provided a lot of flexibility on how to structure and format your documentation. However, I felt that I was spending too much time producing the documentation. One needs to create a configuration file, describe a layout and explicitly add the modules that you wanted to document. If there were a single command option, I couldn’t find it.

I then realized that the problem was that I was trying to use Sphinx for the wrong reasons. I simply wanted to document my API, whereas Sphinx is meant for much more than that. If I ever need to document a project in a more guide kind of a style, Sphinx would be my first choice.

Simple Example

All you need to document an API is to have Python docstrings for your module, class or function. Epydoc supports several kinds of markups that can be used in the docstrings. I like Epytext for its simplicity and the fact the Eclipse IDE is aware of the format of the field descriptors. If you want something more expressive, Epydoc recommends reStructuredText.

The following example is from Epydocs’s site, which uses the Epytext markup.

#python Epydoc docstring for a function http://epydoc.sourceforge.net/manual-epytext.html
def x_intercept(m, b):
        """
        Return the x intercept of the line M{y=m*x+b}.  The X{x intercept}
        of a line is the point at which it crosses the x axis (M{y=0}).

        This function can be used in conjuction with L{z_transform} to
        find an arbitrary function's zeros.

        @type  m: number
        @param m: The slope of the line.
        @type  b: number
        @param b: The y intercept of the line.  The X{y intercept} of a
                            line is the point at which it crosses the y axis (M{x=0}).
        @rtype:   number
        @return:  the x intercept of the line M{y=m*x+b}.
        """
        return -b/m

#python Epydoc docstring for a function http://epydoc.sourceforge.net/manual-epytext.html

def x_intercept(m, b):

"""

Return the x intercept of the line M{y=m*x+b}. The X{x intercept}

of a line is the point at which it crosses the x axis (M{y=0}).

This function can be used in conjuction with L{z_transform} to

find an arbitrary function's zeros.

@type m: number

@param m: The slope of the line.

@type b: number

@param b: The y intercept of the line. The X{y intercept} of a

line is the point at which it crosses the y axis (M{x=0}).

@rtype: number

@return: the x intercept of the line M{y=m*x+b}.

"""

return -b/m

The docstring above generates this output

How To Generate Javadoc Style Documentation For Python

Simple Example

A Biography Of The Power Symbol

Maintaining Read More Links When Moving From Drupal To Jekyll