Use module docstrings and create reference

This is a quick howto reference to show how we should integrate module docstrings in the book and how we create reference between modules.

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:

:func: ...