aircraft-operations-lab / metintos Goto Github PK

The first line is brief explanation, which may be completed with 
a longer one. For instance to discuss about its methods. The only
method here is :func:`function1`'s. The main idea is to document
the class and methods's arguments with 

- **parameters**, **types**, **return** and **return types**::

      :param arg1: description
      :param arg2: description
      :type arg1: type description
      :type arg1: type description
      :return: return description
      :rtype: the return type description

- and to provide sections such as **Example** using the double commas syntax::

      :Example:

      followed by a blank line !

  which appears as follow:

  :Example:

  followed by a blank line

- Finally special sections such as **See Also**, **Warnings**, **Notes**
  use the sphinx syntax (*paragraph directives*)::

      .. seealso:: blabla
      .. warnings also:: blabla
      .. note:: blabla
      .. todo:: blabla

.. note::
    There are many other Info fields but they may be redundant:
        * param, parameter, arg, argument, key, keyword: Description of a
          parameter.
        * type: Type of a parameter.
        * raises, raise, except, exception: That (and when) a specific
          exception is raised.
        * var, ivar, cvar: Description of a variable.
        * returns, return: Description of the return value.
        * rtype: Return type.

.. note::
    There are many other directives such as versionadded, versionchanged,
    rubric, centered, ... See the sphinx documentation for more details.

Here below is the results of the :func:`function1` docstring.

"""

def function1(self, arg1, arg2, arg3):
    """returns (arg1 / arg2) + arg3

    This is a longer explanation, which may include math with latex syntax
    :math:`\\alpha`.
    Then, you need to provide optional subsection in this order (just to be
    consistent and have a uniform documentation. Nothing prevent you to
    switch the order):

      - parameters using ``:param <name>: <description>``
      - type of the parameters ``:type <name>: <description>``
      - returns using ``:returns: <description>``
      - examples (doctest)
      - seealso using ``.. seealso:: text``
      - notes using ``.. note:: text``
      - warning using ``.. warning:: text``
      - todo ``.. todo:: text``

    **Advantages**:
     - Uses sphinx markups, which will certainly be improved in future
       version
     - Nice HTML output with the See Also, Note, Warnings directives


    **Drawbacks**:
     - Just looking at the docstring, the parameter, type and  return
       sections do not appear nicely

    :param arg1: the first value
    :param arg2: the first value
    :param arg3: the first value
    :type arg1: int, float,...
    :type arg2: int, float,...
    :type arg3: int, float,...
    :returns: arg1/arg2 +arg3
    :rtype: int, float

    :Example:

    >>> import template
    >>> a = template.MainClass1()
    >>> a.function1(1,1,1)
    2

    .. note:: can be useful to emphasize
        important feature
    .. seealso:: :class:`MainClass2`
    .. warning:: arg2 must be non-zero.
    .. todo:: check that arg2 is non zero.
    """
    return arg1/arg2 + arg3