Documenting the code

Using Sphinx doc

  • sphinx-quickstart
  • edit the conf.py
    • default-role: literal
    • language: en
    • extensions:
      • autodoc
      • coverage
      • viewcode
.. default-role:: literal
.. highlightlang:: python

Titles level

Use the equal for first level title

=======

Use dash for second level title

----

Use tilde for third level title

~~~~

Lists

Please use - instead of * for the bullet lists

Documenting the code

Documenting a function

Have a look at the python domain to learn how to document a function with sphinx

Here is an example of an output of the documentation of a function

python send_message(sender, recipient, message_body, [priority=1])

Send a message to a recipient

Parameters:
  • sender (str) – The person sending the message
  • recipient (str) – The recipient of the message
  • message_body (str) – The body of the message
  • priority (integer or None) – The priority of the message, can be a number 1-5
Returns:

the message id
Return type:

int
Raises:
  • ValueError – if the message_body exceeds 160 characters
  • TypeError – if the message_body is not a basestring

And here is the source

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
"""

Another example of a docstring:

"""
    finds a list of options recursively in the config

    :param bytype: Option class (BoolOption, StrOption, ...)
    :param byname: filter by Option._name
    :param byvalue: filter by the option's value
    :returns: list of matching Option objects
"""

Documenting a class

  • What the class does : in the class’ docstring
  • What are the parameters during the object’s instanciation : in the __init__ method.

Code coverage

TODO: You can use sphynx for the code coverage