Here follows a recap of main syntax.

Examples

Parameters

Describe what it does and how!

Choose what you enjoy the most, Sphinx support all of them via napoleon module.

rst style

See doc for more keywords

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    :param int arg1: Description of arg1.
    :param str arg2: Description of arg2.
    :raises ValueError if arg1 is equal to arg2
    :return: Description of return value
    :rtype: bool
    """

google style

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    Raises:
        AttributeError: The ``Raises`` section is a list of all exceptions
            that are relevant to the interface.
        ValueError: If `arg2` is equal to `arg1`.

    Examples:
        Examples should be written in doctest format, and should illustrate how
        to use the function.

        >>> a=[1,2,3]
        >>> print [x + 3 for x in a]
        [4, 5, 6]

    """

Numppy style

def random_number_generator(arg1, arg2):
    """
    Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    int
        Description of return value

    Raises
    ------
    AttributeError
        The ``Raises`` section is a list of all exceptions
        that are relevant to the interface.

    """
    return 42

Usage

Show inline usage (could be use also as a unittest thanks to doctest!)

def my_func(a, b):
    """
    >>> my_func(2, 4)
    8
    >>> my_func("a", 3)
    'aaa'
    """



if __name__ == "__main__":
    import doctest
    doctest.testmod()

Webography

MyWiki: Documentazione Python (last edited 2018-07-19 07:52:52 by risca)