2.4 Documentation Strings

Every function must have a docstring that includes the following information:

A one-sentence description of the function, followed by a blank line.

An INPUT and an OUTPUT block for input and output arguments (see below for format). The type names should be descriptive, but do not have to represent the exact Sage/Python types. For example, use ``integer'' for anything that behaves like an integer; you do not have to put a precise type name such as int.

An EXAMPLES block for examples. This is not optional. These examples are used for automatic testing before each release and new functions without these doctests will not be accepted for inclusion with Sage.

An ALGORITHM block (optional) which indicates what software and/or what algorithm is used. For example ALGORITHM: Uses Pari.

A NOTES block for special notes (optional). Include information such as references, purpose etc.

An AUTHORS block (optional, but encouraged for important functions, so users can see from the docstring who wrote it and therefore whom to contact if they have questions).

def point(self, x=1, y=2):
    r"""
    This function returns the point $(x^5,y)$.

    INPUT:
        x -- integer (default: 1) the ...
        y -- integer (default: 2) the ...

    OUTPUT:
        integer -- the ...

    EXAMPLES:
    This example illustrates ...
        sage: A = ModuliSpace()
        sage: A.point(2,3)
        xxx

    We now ...
        sage: B = A.point(5,6)
        sage: xxx

    It is an error to ...
        sage: C = A.point('x',7)
        Traceback (most recent call last):
        ...
        TypeError: unable to convert x (=r) to an integer

    NOTES:
        This function uses the algorithm of [BCDT] to determine whether
        an elliptic curve E over Q is modular.

        ...

        REFERENCES:
             [BCDT] Breuil, Conrad, Diamond, Taylor, "Modularity ...."

    AUTHORS: 
        - William Stein (2005-01-03)
        - First_name Last_name (yyyy-mm-dd)
    """
    <body of the function>

strongly encouraged

Use nice LaTeX formating everywhere. If you use backslashes, either 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)$.
    """

Also, the non-standard LaTeX 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 a patch file on the Sage trac server (Chapter 9) so that they can be included in the next version of Sage.

Liberally describe what the examples do. Note that there must be a blank line after the example code and before the explanatory text for the next example (indentation isn't enough).

Illustrate any exceptions raised by the function with examples, as given above (It is an error to ...; In particular, use ...).

Include many examples. These are automatically tested on a regular basis, and are crucial for the quality and adaptability of Sage. Without such examples, small changes to one part of Sage that break something else might not go seen until much later when someone uses the system, which is unacceptable. Note that no new functions without will be accepted for inclusion in Sage.

The code in the examples should pass automatic testing. This means that if the above code is in the file f.py (or f.sage), then sage -t f.py should not give any error messages. Testing occurs with full Sage preparsing of input within the standard Sage shell environment, as described in Section 3.3. Important: The file f.py is not imported when running tests unless you have arranged that it be imported into your Sage environment, i.e., unless its functions are available when you start Sage using the sage command. For example, the function cdd_convert in the file SAGE_ROOT/devel/sage/sage/geometry/polyhedra.py includes an EXAMPLES block containing the following:

    sage: from sage.geometry.polyhedra import cdd_convert
    sage: cdd_convert(' 1 1 0 0')
    [1, 1, 0, 0]

Sage

cdd_convert

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