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 withparameters, 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:
- Returns:
arg1/arg2 +arg3
- Return type:
- 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.