Documentation and style guideline exampleΒΆ

# -*- coding: utf-8 -*-

# This guide follows mostly: 
# https://github.com/numpy/numpy/blob/master/doc/example.py
"""
Here comes the module description

Detailed introduction and tutorial of method goes here.

You can even link tutorials here, if appropiate. 

If you have references you can insert them here, otherwise in the corresponding
funtions, methods or classes.

For a working example see :py:mod:`unitary_event_analysis.py<elephant.unitary_event_analysis>`
"""

class MyClass(object):  # Classes use CamelCase notation
    """
    One line description of class.

    Long description of class, may span several lines. Possible sections:

    Parameters
    ----------
    List the arguments of the constructor (__init__) here!
    
    x : float
        The X coordinate
    y : float
        The Y coordinate
  
    Raises
    ------
    ...

    See Also
    --------
    ...

    Notes
    -----
    ...

    References
    ----------
    ...

    Examples
    --------
    ...

    Methods
    -------
    Only list methods if the class is very complex
    """

    def __init__(self, param):
        """
        Constructor
        (actual documentation is in class documentation, see above!)
        """
        self.param = param

    def function_a(self, param, spiketrains, is_true=True, c='C', var=None):
        """
        One-line short description of the function.

        Long description of the function. Details of what the function is doing
        and how it is doing it. Used to clarify functionality, not to discuss
        implementation detail or background theory, which should rather be
        explored in the notes section below. You may refer to the parameters
        and the function name, but parameter descriptions still belong in the
        parameters section.

        Variable, module, function, and class names should be written
        between single back-ticks (`numpy`), NOT *bold*.

        Parameters
        ----------
        param : int or float
            Description of parameter `param`. Enclose variables in single
            backticks. The colon must be preceded by a space, or omitted if the
            type is absent.
        spiketrains : list of neo.SpikeTrain objects
            A list to copy all strings in the world.
        is_true :
            True, if 1.
            False, if 0.
            Default is True.
        c : 'C', 'F', 'A'
            If only certain values are allowed. 
            Default is 'C'.
        var : int
            Some value. 
            Default is `None`

        Returns
        -------
        signal : int
            Description of return value.
        list : list of numpy.array
            Returns a list of numpy.arrays. 

        Raises
        ------
        ValueError :
            Condition when a ValueError can occur.

        See Also
        --------
        average : Weighted average
            Used to refer to related code. Functions may be listed without 
            descriptions, and this is preferable if the functionality is 
            clear from the function name.
            scipy.random.norm : Random variates, PDFs, etc.

        Notes
        -----
        An optional section that provides additional information about the
        code, possibly including a discussion of the algorithm. This section
        may include mathematical equations, written in LaTeX format. Inline:
        :math: `x^2`. An equation:

        .. math::

        x(n) * y(n) \Leftrightarrow X(e^{j\omega } )Y(e^{j\omega } )\\
        another equation here

        Images are allowed, but should not be central to the explanation; users
        viewing the docstring as text must be able to comprehend its meaning
        without resorting to an image viewer. These additional illustrations
        are included using:

        .. image:: filename

        References
        ----------
        .. [1] O. McNoleg, "The integration of GIS, remote sensing ... "

        Examples
        --------
        These are written in doctest format, and should illustrate how to
        use the function. This text may explain the example beforehand.

        >>> np.add(1, 2)
        3

        >>> import numpy as np
        >>> import numpy.random
        >>> np.random.rand(2)
        array([ 0.35773152,  0.38568979])  #random

        """

        # Variables use underscore notation
        dummy_variable = 1
        a = 56  # This mini comment uses two spaces after the code!

        # Textual strings use double quotes
        error = "An error occurred. Please fix it!"

        # Non-textual strings use single quotes
        default_character = 'a'

        # Normal comments are proceeded by a single space, and begin with a
        # capital letter
        dummy_variable += 1

        # Longer comments can have several sentences. These should end with a
        # period. Just as in this example.
        dummy_variable += 1

    # Class functions need only 1 blank line.
    # This function is deprecated. Add a warning!
    def function_b(self, **kwargs):
        """
        This is a function that does b.

        .. note:: Deprecated in elephant 0.4
          `function_b` will be removed in elephant 1.0, it is replaced by
          `function_c` because the latter works also with Numpy Ver. 1.6.

        Parameters
        ----------
        kwargs: {divide, over, under, invalid}
            From numpy.errstate.
            Keyword arguments. The valid keywords are the
            possible floating-point exceptions. Each keyword should have a
            string value that defines the treatment for the particular error.
            Possible values are {'ignore', 'warn', 'raise', 'call', 'print',
            'log'}.

        """
        pass


class MyOtherClass(object):
    """
    Class documentation
    """

    def __init__(self, params):
        """
        Constructor
        """

        pass


# Functions also need 2 blank lines between any structures.
def top_level_function(param):
    """
    The same docstring guidelines as in the class above.
    """
    pass


def another_top_level_function(param):
    """
    The same docstring guidelines as in the class above.
    """
    pass