A Brief Introduction to Epytext

Epytext is a simple lightweight markup language that lets you add formatting and structure to docstrings. Epydoc uses that formatting and structure to produce nicely formatted API documentation. The following example (which has an unusually high ratio of documentaiton to code) illustrates some of the basic features of epytext:

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

You can compare this function definition with the API documentation generated by epydoc. Note that:

• Paragraphs are separated by blank lines.
• Inline markup has the form "x{...}", where "x" is a single capital letter. This example uses inline markup to mark mathematical expressions ("M{...}"); terms that should be indexed ("X{...}"); and links to the documentation of other objects ("L{...}").
• Descriptions of parameters, return values, and types are marked with "@field:" or "@field arg:", where "field" identifies the kind of description, and "arg" specifies what object is described.

For more information about the epytext markup language, see the epytext manual. Epytext is intentionally very lightweight. If you wish to use a more expressive markup language, I recommend reStructuredText.