formations/python/python3/en/documenting.txt

86 lines
2.8 KiB
Plaintext

Technical an user documentation
================================
- documenting_
.. _documenting: https://realpython.com/documenting-python-code/
The sphinx_ tool is a subset of docutils_
.. _sphinx: http://sphinx-doc.org/
.. _docutils: http://docutils.sf.net
Documenting a function
------------------------
**Info field lists**
Inside Python object description directives, reST field lists with these fields are recognized and formatted nicely:
- param, parameter, arg, argument, key, keyword: Description of a parameter.
- type: Type of a parameter. Creates a link if possible.
- raises, raise, except, exception: That (and when) a specific exception is raised.
- var: Description of a variable.
- vartype: Type of a variable. Creates a link if possible.
- returns, return: Description of the return value.
- rtype: Return type. Creates a link if possible.
The field names must consist of one of these keywords and an argument (except for returns and rtype, which do not need an argument). This is best explained by an example:
::
.. py:function:: send_message(sender, recipient, message_body, [priority=1])
Send a message to a recipient
:param str sender: The person sending the message
:param str recipient: The recipient of the message
:param str message_body: The body of the message
:param priority: The priority of the message, can be a number 1-5
:type priority: integer or None
:return: the message id
:rtype: int
:raises ValueError: if the message_body exceeds 160 characters
:raises TypeError: if the message_body is not a basestring
This will render like this with spinx-doc:
.. py:function:: send_message(sender, recipient, message_body, [priority=1])
Send a message to a recipient
:param str sender: The person sending the message
:param str recipient: The recipient of the message
:param str message_body: The body of the message
:param priority: The priority of the message, can be a number 1-5
:type priority: integer or None
:return: the message id
:rtype: int
:raises ValueError: if the message_body exceeds 160 characters
:raises TypeError: if the message_body is not a basestring
It is also possible to combine parameter type and description, if the type is
a single word, like this::
:param int priority: The priority of the message, can be a number 1-5
Container types such as lists and dictionaries can be linked automatically
using the following syntax::
:type priorities: list(int)
:type priorities: list[int]
:type mapping: dict(str, int)
:type mapping: dict[str, int]
:type point: tuple(float, float)
:type point: tuple[float, float]
Multiple types in a type field will be linked automatically if separated by
the word “or”::
:type an_arg: int or None
:vartype a_var: str or int
:rtype: float or str