Deeper look on the template files#

So, the custom template files I recommend in Adding and using Sphinx in your project are:

custom-module-template.rst#
 1{{ name }} {{ objtype[0] | upper }}{{ objtype[1:] }}
 2{{ '=' * ( (name + objtype) | length + 1 ) }}
 3
 4.. automodule:: {{ fullname }}
 5   :no-members:
 6
 7{% block attributes %}
 8{% if attributes %}
 9.. rubric:: Module Attributes
10
11.. autosummary::
12   :toctree:
13{% for item in attributes %}
14   {{ item }}
15{%- endfor %}
16{% endif %}
17{% endblock %}
18
19{% block functions %}
20{% if functions %}
21.. rubric:: {{ _('Functions') }}
22
23.. autosummary::
24   :toctree:
25   :template: custom-object-template.rst
26{% for item in functions %}
27   {{ item }}
28{%- endfor %}
29{% endif %}
30{% endblock %}
31
32{% block classes %}
33{% if classes %}
34.. rubric:: {{ _('Classes') }}
35
36.. autosummary::
37   :toctree:
38   :template: custom-object-template.rst
39{% for item in classes %}
40   {{ item }}
41{%- endfor %}
42{% endif %}
43{% endblock %}
44
45{% block exceptions %}
46{% if exceptions %}
47.. rubric:: {{ _('Exceptions') }}
48
49.. autosummary::
50   :toctree:
51{% for item in exceptions %}
52   {{ item }}
53{%- endfor %}
54{% endif %}
55{% endblock %}
56
57{% block modules %}
58{% if modules %}
59.. rubric:: Modules
60
61.. autosummary::
62   :toctree:
63   :template: custom-module-template.rst
64   :recursive:
65{% for item in modules %}
66   {{ item }}
67{%- endfor %}
68{% endif %}
69{% endblock %}
custom-object-template.rst#
 1{{ name }} {{ objtype[0] | upper }}{{ objtype[1:] }}
 2{{ '=' * ( (name + objtype) | length + 1 ) }}
 3
 4.. currentmodule:: {{ module }}
 5
 6{% if objtype == 'function' %}
 7.. autofunction:: {{ objname }}
 8{% endif %}
 9
10{% if objtype == 'class' %}
11.. autoclass:: {{ objname }}
12   :members:
13   :show-inheritance:
14   :inherited-members:
15{% endif %}

As you can see, the template files are reStructuredText files written using the Jinja templating engine syntaxis and reStructuredText. They contain the instructions to automatically document any file.

See also

  1. Sphinx support for Jinja syntaxis

  2. Jinja Template Designer Documentation

  3. Sphinx templating documentation

Primer on the syntaxis#

First of all, we need to understand some basics of the syntaxis used on the Template files.

Jinja syntaxis#

First of all its important to undestand the importance of Jinja delimiters. There are three of them:

  • {% ... %} for statements.

  • {{ ... }} for expressions to print to the template output.

  • {# ... #} for comments not included in the template output.

Maybe the more important of these is the statements syntaxis, as they allow for neat things such as:

  • if statements:

    The if statement in Jinja is comparable with the Python if statement.

    {% if kenny.sick %}
   ...
{% elif kenny.dead %}
   ...
{% else %}
   ...
{% endif %}

  • for statements:

    The for statements in Jinja works somewhat like Python for statements, the most important differences are that dictionaries are not sorted by default and the break and continue don’t work.

    {% for user in users %}
   ...
{% endfor %}

  • Many other! Check out the list of control structures.

Jinja filters#

With Jinja you can also use filters, similar to the way you use pipelines on Unix systems. For example, this prints the uppercase of the first letter of a variable

{{ variable[0] | upper }}

You can find a full list of the built-in filters here.

Sphinx global variables for Jinja#

On the other hand, Sphinx support the following global variables to be used with Jinja syntaxis, all of them can be “called” vía { sphinx_global_variable } or {{ sphinx_global_variable }} if you want to print them in the template.

  • name: Name of the documented object, excluding the module and class parts.

  • objname: Name of the documented object, excluding the module parts.

  • fullname: Name of the documented object, including the module and class parts.

  • module: Name of the module the documented object belongs to.

  • underline: A string containing len(full_name) * '='. Use the underline filter instead.

  • attributes: List containing names of “public” attributes in the class/module. Only available for classes and modules.

  • functions: List containing names of “public” functions in the module. Here, “public” means that the name does not start with an underscore. Only available for modules.

  • classes: List containing names of “public” classes in the module. Only available for modules.

  • modules: List containing names of “public” methods in the class. Only available for classes.

  • exceptions: List containing names of “public” exceptions in the module. Only available for modules.

Understanding the Template files#

To fully understand the template files, we will analyze them separately and separate them into each of their sections.

The object template file#

The object template file is the simplest of the two templates that we will analyze. It can be divided into the three main sections highlighted below:

custom-object-template.rst#
 1{{ name }} {{ objtype[0] | upper }}{{ objtype[1:] }}
 2{{ '=' * ( (name + objtype) | length + 1 ) }}
 3
 4.. currentmodule:: {{ module }}
 5
 6{% if objtype == 'function' %}
 7.. autofunction:: {{ objname }}
 8{% endif %}
 9
10{% if objtype == 'class' %}
11.. autoclass:: {{ objname }}
12   :members:
13   :show-inheritance:
14   :inherited-members:
15{% endif %}

Suppose that a function example_function() is going to be documented with this template, then:

Print the title of the file:

  • Line 1 prints out the name of the object (in this case “example_function”), then adds a space and print the object type formatted (in this case “function”) with the first letter uppercased and the rest without changes.

  • Line 2 adds a underline of = with the lenght of the string, making it a section.

custom-object-template.rst lines 6 to 8#
6{% if objtype == 'function' %}
7.. autofunction:: {{ objname }}
8{% endif %}

Check out if the object is a function, in that case, prints out its docstrings. (this would been print out in our example_function() case)

custom-object-template.rst lines 10 onwards#
10{% if objtype == 'class' %}
11.. autoclass:: {{ objname }}
12   :members:
13   :show-inheritance:
14   :inherited-members:
15{% endif %}

Check out if the object is a class, in that case, prints out its docstrings showing its methods, inheritance and its inherited members (this would not print anything in our example_function() case)

The module template file#

The module template file can be divided into the following main sections highlighted below:

custom-module-template.rst#
 1{{ name }} {{ objtype[0] | upper }}{{ objtype[1:] }}
 2{{ '=' * ( (name + objtype) | length + 1 ) }}
 3
 4.. automodule:: {{ fullname }}
 5   :no-members:
 6
 7{% block attributes %}
 8{% if attributes %}
 9.. rubric:: Module Attributes
10
11.. autosummary::
12   :toctree:
13{% for item in attributes %}
14   {{ item }}
15{%- endfor %}
16{% endif %}
17{% endblock %}
18
19{% block functions %}
20{% if functions %}
21.. rubric:: {{ _('Functions') }}
22
23.. autosummary::
24   :toctree:
25   :template: custom-object-template.rst
26{% for item in functions %}
27   {{ item }}
28{%- endfor %}
29{% endif %}
30{% endblock %}
31
32{% block classes %}
33{% if classes %}
34.. rubric:: {{ _('Classes') }}
35
36.. autosummary::
37   :toctree:
38   :template: custom-object-template.rst
39{% for item in classes %}
40   {{ item }}
41{%- endfor %}
42{% endif %}
43{% endblock %}
44
45{% block exceptions %}
46{% if exceptions %}
47.. rubric:: {{ _('Exceptions') }}
48
49.. autosummary::
50   :toctree:
51{% for item in exceptions %}
52   {{ item }}
53{%- endfor %}
54{% endif %}
55{% endblock %}
56
57{% block modules %}
58{% if modules %}
59.. rubric:: Modules
60
61.. autosummary::
62   :toctree:
63   :template: custom-module-template.rst
64   :recursive:
65{% for item in modules %}
66   {{ item }}
67{%- endfor %}
68{% endif %}
69{% endblock %}

If you notice, the first two lines are the same as the template-titlelines in the previous file so I’ll omit them from the explanation.

On the other hand, lines 4 and 5 get the docstrings of the module, nevertheles the :no-members: flag prevents that any of the objects docstrings (either attributes, functions, etc) get printed out in the file, so this lines only print out the module-level docstrings.

The further blocks of code, do all the same but for different elements inside the module (if you note, the structure of lines 7 to 17 is the same as 19 to 30 or 32 to 43 and so on) so we’ll be focusing only on one of them.

custom-module-template.rst#
 1{% block functions %}
 2{% if functions %}
 3.. rubric:: {{ _('Functions') }}
 4
 5.. autosummary::
 6   :toctree:
 7   :template: custom-object-template.rst
 8{% for item in functions %}
 9   {{ item }}
10{%- endfor %}
11{% endif %}
12{% endblock %}

The block tag in simple words calls or defines a child template to take its place. In this case, the child template is defined inside the block in lines 2 to 11.

The if statement is here to only build the block if the type of object is present inside the module (in this case “functions”). Line 3 creates a paragraph heading that is not used to create a TOC node.

Finally, lines 5 to 10 creates a autosummary table generating a page for every element (in this case every function in the module) using the custom-module-template.rst template file.