4.1 Source Code Documentation

Use LaTeX formatting in the documentation string. If you wish to use backslashes in the documentation string, use double backslashes or place an r right before the first triple opening quote. For example,
def cos(x):
    """
    Returns $\\cos(x)$.
    """

def sin(x):
    r"""
    Returns $\sin(x)$.
    """

The non-standard macros that are used when typesetting the documentation are defined in SAGE_ROOT/doc/commontex/macros.tex. If you need to add more macros, add them there and post them on the sage-devel Google group so that they can be included in the next version of Sage.

The first line two or three lines of the docstring should briefly summarize what the function does, e.g., ``Returns X'' or ``Computes X'', or ``Creates a new X''. Next describe the input and output of the function using the following notation:

INPUT:
    var1 -- <type> (default: ...) description
    var2 -- <type> (default: ...) description
    etc.

OUTPUT: 
    <type> -- description of return value 1
    <type> -- description of return value 2
    etc.

This is a placeholder of a "Perfect example of the above".

For consistency you should use the above format, which is used throughout the system. Do not just describe the input and output in long sentences. For methods of a class, whether or not to describe self is up to you; this can be useful if self must have some special properties. Also, you do not have to specify the types of the input and output arguments precisely; e.g., use ``integer'' for an int or long or Sage Integer.

Every function should have at least one, and preferably many, examples that illustrate its usage. These examples must exactly match the output of an actual running copy of Python. To test whether this is the case, run the program sage -t with your Python or Cython file as unique argument (see Chapter 4.3 for more details).

For more details, see Section 2.4.

See About this document... for information on suggesting changes.