Use module docstrings and create reference

Include module docstrings

Sphinx uses interpreted text roles to insert semantic markup into documents. We use the Sphinx directive called :automodule to do so that points on the module name.

For example, if your chapter concerns a module. Please add the following line in you sphinx file to retrieve automatically the module docstring:

• .. automodule:: <module_name>

mod: is a role to link to name of a module inside documentation.

The syntax to use is:

The module :mod:`<module_name>` is ... blablabla...

Of course, You have some other useful directives as:

• .. autoclass:: <class_name>
• .. autofunction:: <function_name>

Create arbitrary references

Sphinx let you reference arbitrary locations by using new :ref: directive

Only a section could be an anchor that can be referenced. To create a reference do as follow:

.. _my-section:

Section title goes here
-----------------------

Then, to create a link in your docstring to your section, use :ref:`my-section` or :ref:`Link title <my-section>` for reference.

Don't use standard ReST hyperlink notation because it doesn't work with multi-document.

Create reference between python objects

You can reference module or class by different directives:

:mod:`cubicweb.selectors`
:class:`cubicweb.selectors.EntitySelector`
:func: ...

References

• liste des paramètres
• autodoc
• autosummary
• http://packages.python.org/an_example_pypi_project/sphinx.html

Caveats

• doctest on autofunction does is hidden with certain decorators