Skip to content
Snippets Groups Projects

document_code

Last edited by Florent Jaillet

How to document the code in ltfatpy

This page is intended for the ltfatpy developers and describes the convention used to document the code of ltfatpy.

Syntax

The ltfatpy documentation is generated using sphinx, so all the docstrings must be written using the syntax recognized by sphinx, which is documented here and here.

Documenting modules

At the beginning of each module (so at the beginning of each file), add a short docstring describing the content of the module, and add the module author(s) name(s) without any e-mail address (a main e-mail address for contact is given in the main page of the documentation).

Add a line identifying the octave file name and the version of ltfat used for porting the file.

Example:

""" Module of frequency index of FFT modulations computation

Ported from ltfat_2.1.0/fourier/fftindex.m

.. moduleauthor:: Florent Jaillet
"""

Documenting functions

Each function should have a docstring documenting its use and behaviour.

As much as possible, document the content of the inputs and outputs of the functions, including their data types.

Usage

For this, you can keep and adapt the "usage" section found in the ltfat octave function. Use | before each usage line like this:

- Usage:
    
        | ``(c, Ls, g) = dgt(f, g, a, M)``
        | ``(c, Ls, g) = dgt(f, g, a, M, L)``
        | ``(c, Ls, g) = dgt(f, g, a, M, L, pt)``

Input parameters

To document the inputs, use the fields param and type to describe each input. When the data type is a single word, use the following compact syntax:

:param int a: Length of time shift

When the type is more complex, use the type field like this:

:param g: Window function
:type g: str, dict or numpy.ndarray of float64 or complex128

To specify the type of numpy arrays use the following syntax (specifying the dtype and number of dimensions is optional):

numpy.ndarray of float64 with ndim=3

Output parameters

To document the outputs, use the returns, rtype, var, vartype fields.

If the function returns a single value, there is no need to name the output and you can use only returns and rtype.

If the function returns multiple values, use the following type of syntax:

- Output parameters:

    :returns: ``(g, info)``
    :rtype: tuple

    :var numpy.ndarray g: the computed window
    :var dict info: the information dictionary

Exceptions

If needed, you can also document the exception raised by the function using the raises field.

Indentation

Note that all the fields param, type, returns, rtype, var, vartype and raises must be indented at the same level than the opening of the docstring to be interpreted as they should by sphinx. That is to say that the following works:

def lcm(X, Y):
    """Compute the least common multiple
    
    - Inputs:
    
    :param int X: The first of the two integers for which to compute the
                  least common multiple
    :param int Y: The second of the two integers for which to compute the
                  least common multiple
    
    - Outputs:
    
    :returns: the least common multiple of **X** and **Y**
    :rtype: int
    
    """
    if not isinstance(X, int) or not isinstance(Y, int):
        raise TypeError('X and Y must be int.')
    
    return X * Y // gcd(X, Y)

while the following doesn't work:

def lcm(X, Y):
    """Compute the least common multiple
    
    - Inputs:
    
        :param int X: The first of the two integers for which to compute the
                      least common multiple
        :param int Y: The second of the two integers for which to compute the
                      least common multiple
    
    - Outputs:
    
        :returns: the least common multiple of **X** and **Y**
        :rtype: int
    
    """
    if not isinstance(X, int) or not isinstance(Y, int):
        raise TypeError('X and Y must be int.')
    
    return X * Y // gcd(X, Y)

Functions, parameters and code highlighting

In the docstrings, use the references to functions when needed, highlight the input parameters in bold, and highlight any code or value using literal, as in this example where order is a parameter:

    ``assert_groworder`` is meant to be used in conjunction with
    :func:`~ltfatpy.comp.assert_sigreshape_pre.assert_sigreshape_pre` and 
    :func:`~ltfatpy.comp.assert_sigreshape_post.assert_sigreshape_post`. It is
    used to modify the **order** parameter in between calls in order to expand 
    the processed dimension by ``1``, i.e. for use in a routine that creates 2D
    output from 1D input, for instance in :func:`~ltfatpy.gabor.dgt.dgt` or 
    :func:`filterbank`.

See also

To add a "See also" section in a docstring, use the following syntax:

    .. seealso:: :func:`~ltfatpy.gabor.dgt.dgt`,
        :func:`~ltfatpy.gabor.tfplot.tfplot`,
        :func:`~ltfatpy.gabor.sgram.sgram`,
        :func:`~ltfatpy.gabor.plotdgtreal.plotdgtreal`

Notes

To add a "Note" section in a docstring, use the following syntax:

    .. note::
        If soft- or Wiener thresholding is selected, only ``N-1``
        coefficients will actually be returned. This is caused by the Nth
        coefficient being set to zero.

References and bibliography

The bibliography is handled using sphinxcontrib-bibtex.

To add a reference in a docstring, use the following syntax, where the references identifiers are the one used in the bibtex file:

    - References:
        :cite:`fest98,gr01`

Comments

    Please register or sign in to add a comment.