86 lines
2.8 KiB
Plaintext
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
|