code_examples.reST_docstrings_example.MainClass1#

class code_examples.reST_docstrings_example.MainClass1#

Bases: object

This class docstring shows how to use sphinx and rst syntax

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 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 function1() docstring.

Public Methods:

function1(arg1, arg2, arg3)

returns (arg1 / arg2) + arg3


__dict__ = mappingproxy({'__module__': 'code_examples.reST_docstrings_example', '__doc__': "This class docstring shows how to use sphinx and rst syntax\n\n    The first line is brief explanation, which may be completed with\n    a longer one. For instance to discuss about its methods. The only\n    method here is :func:`function1`'s. The main idea is to document\n    the class and methods's arguments with\n\n    - **parameters**, **types**, **return** and **return types**::\n\n          :param arg1: description\n          :param arg2: description\n          :type arg1: type description\n          :type arg1: type description\n          :return: return description\n          :rtype: the return type description\n\n    - and to provide sections such as **Example** using the double commas syntax::\n\n          :Example:\n\n          followed by a blank line !\n\n      which appears as follow:\n\n      :Example:\n\n      followed by a blank line\n\n    - Finally special sections such as **See Also**, **Warnings**, **Notes**\n      use the sphinx syntax (*paragraph directives*)::\n\n          .. seealso:: blabla\n          .. warnings also:: blabla\n          .. note:: blabla\n          .. todo:: blabla\n\n    .. note::\n        There are many other Info fields but they may be redundant:\n            * param, parameter, arg, argument, key, keyword: Description of a\n              parameter.\n            * type: Type of a parameter.\n            * raises, raise, except, exception: That (and when) a specific\n              exception is raised.\n            * var, ivar, cvar: Description of a variable.\n            * returns, return: Description of the return value.\n            * rtype: Return type.\n\n    .. note::\n        There are many other directives such as versionadded, versionchanged,\n        rubric, centered, ... See the sphinx documentation for more details.\n\n    Here below is the results of the :func:`function1` docstring.\n\n    ", 'function1': <function MainClass1.function1>, '__dict__': <attribute '__dict__' of 'MainClass1' objects>, '__weakref__': <attribute '__weakref__' of 'MainClass1' objects>, '__annotations__': {}})#
__module__ = 'code_examples.reST_docstrings_example'#
function1(arg1, arg2, arg3)#

returns (arg1 / arg2) + arg3

This is a longer explanation, which may include math with latex syntax \(\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

Parameters:
  • arg1 (int, float,...) – the first value

  • arg2 (int, float,...) – the first value

  • arg3 (int, float,...) – the first value

Returns:

arg1/arg2 +arg3

Return type:

int, float

Example:

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

Note

can be useful to emphasize important feature

See also

MainClass2

Warning

arg2 must be non-zero.