Use module docstrings and create reference
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:
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:
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.
You can reference module or class by different directives:
:mod:`cubicweb.selectors` :class:`cubicweb.selectors.EntitySelector` :func: ...