sphinxcontrib.datatemplates — Render Your Data Readable

sphinxcontrib.datatemplates helps you use static data in machine readable format in your documentation by letting you define Jinja2 templates to turn JSON, YAML, XML, or CSV data into reStructuredText for Sphinx to render as part of its output.

Using datatemplate

The datatemplate directive is the interface between the data source and the rendering template. It requires two parameters.

.. datatemplate:json::

Load source via json.load()

.. datatemplate:yaml::

Load source via PyYAML (yaml.safe_load)

.. datatemplate:xml::

Load source via xml.etree.ElementTree.parse() (actually using defusedxml)

.. datatemplate:csv::

Load source via csv.reader() or csv.DictReader depending on header

Template Context

When a datatemplate directive is processed, the data is passed to the template through its context so that the symbol data is available as a global variable.

Important

The data is loaded from the source and passed directly to the template. No pre-processing is done on the data, so the template needs to handle aspects like None values and fields that have values that may interfere with parsing reStructuredText.

Template Helpers

These helper functions are exposed using their short name (without the module prefix) in the template context.

sphinxcontrib.datatemplates.helpers.make_list_table(headers, data, title='', columns=None)

Build a list-table directive.

Parameters:
  • headers – List of header values.
  • data – Iterable of row data, yielding lists or tuples with rows.
  • title – Optional text to show as the table title.
  • columns – Optional widths for the columns.
sphinxcontrib.datatemplates.helpers.make_list_table_from_mappings(headers, data, title, columns=None)

Build a list-table directive.

Parameters:
  • headers – List of tuples containing header title and key value.
  • data – Iterable of row data, yielding mappings with rows.
  • title – Optional text to show as the table title.
  • columns – Optional widths for the columns.

JSON Samples

Data File

{
    "key1": "value1",
    "key2": [
        "list item 1",
        "list item 2",
        "list item 3"
    ],
    "nested-list": [
        ["a", "b", "c"],
        ["A", "B", "C"]
    ],
    "mapping-series": [
        {"cola": "a", "colb": "b", "colc": "c"},
        {"cola": "A", "colb": "B", "colc": "C"}
    ]
}

Template File

.. -*- mode: rst -*-

Static Heading
--------------

Individual Item
~~~~~~~~~~~~~~~

{{ data['key1'] }}

List of Items
~~~~~~~~~~~~~

{% for item in data['key2'] %}
- {{item}}
{% endfor %}

Nested List Table
~~~~~~~~~~~~~~~~~

Rendering a table from a list of nested sequences using hard-coded
headers.

{{ make_list_table(
    ['One', 'Two', 'Three'],
    data['nested-list'],
    title='Table from nested lists',
    ) }}

Mapping Series Table
~~~~~~~~~~~~~~~~~~~~

Rendering a table from a list of nested dictionaries using dynamic
headers.

{{ make_list_table_from_mappings(
    [('One', 'cola'), ('Two', 'colb'), ('Three', 'colc')],
    data['mapping-series'],
    title='Table from series of mappings',
    ) }}

Rendered Output

Static Heading

Individual Item

value1

List of Items
  • list item 1
  • list item 2
  • list item 3
Nested List Table

Rendering a table from a list of nested sequences using hard-coded headers.

Table from nested lists
One Two Three
a b c
A B C
Mapping Series Table

Rendering a table from a list of nested dictionaries using dynamic headers.

Table from series of mappings
One Two Three
a b c
A B C

YAML Samples

Data File

---
key1: value1
key2:
  - list item 1
  - list item 2
  - list item 3
nested-list:
  - ['a', 'b', 'c']
  - ['A', 'B', 'C']
mapping-series:
  - cola: a
    colb: b
    colc: c
  - cola: A
    colb: B
    colc: C

Template File

.. -*- mode: rst -*-

Static Heading
--------------

Individual Item
~~~~~~~~~~~~~~~

{{ data['key1'] }}

List of Items
~~~~~~~~~~~~~

{% for item in data['key2'] %}
- {{item}}
{% endfor %}

Nested List Table
~~~~~~~~~~~~~~~~~

Rendering a table from a list of nested sequences using hard-coded
headers.

{{ make_list_table(
    ['One', 'Two', 'Three'],
    data['nested-list'],
    title='Table from nested lists',
    ) }}

Mapping Series Table
~~~~~~~~~~~~~~~~~~~~

Rendering a table from a list of nested dictionaries using dynamic
headers.

{{ make_list_table_from_mappings(
    [('One', 'cola'), ('Two', 'colb'), ('Three', 'colc')],
    data['mapping-series'],
    title='Table from series of mappings',
    ) }}

Rendered Output

Static Heading

Individual Item

value1

List of Items
  • list item 1
  • list item 2
  • list item 3
Nested List Table

Rendering a table from a list of nested sequences using hard-coded headers.

Table from nested lists
One Two Three
a b c
A B C
Mapping Series Table

Rendering a table from a list of nested dictionaries using dynamic headers.

Table from series of mappings
One Two Three
a b c
A B C

CSV Samples

Data File

a	b	c
Eins	Zwei	Drei
1	2	3
I	II	III

Template File

.. -*- mode: rst -*-

Static Heading
--------------

Individual Cell in Row
~~~~~~~~~~~~~~~~~~~~~~

{{ data[0].a }}

List of Cells in Row
~~~~~~~~~~~~~~~~~~~~

{% for item in data[0].items() %}
- {{item[0]}}: {{item[1]}}
{% endfor %}

Mapping Series Table
~~~~~~~~~~~~~~~~~~~~

Rendering a table from a list of nested dictionaries using dynamic
headers.

{{ make_list_table_from_mappings(
    [('One', 'a'), ('Two', 'b'), ('Three', 'c')],
    data,
    title='Table from series of mappings',
    ) }}

Code

.. datatemplate:csv::
    :source: sample.csv
    :template: csv-sample.tmpl
    :headers:
    :dialect: excel-tab

Rendered Output

Static Heading

Individual Cell in Row

Eins

List of Cells in Row
  • a: Eins
  • b: Zwei
  • c: Drei
Mapping Series Table

Rendering a table from a list of nested dictionaries using dynamic headers.

Table from series of mappings
One Two Three
Eins Zwei Drei
1 2 3
I II III

XML Samples

Data File

<sample>
    <key1>value1</key1>
    <key2>
        <item>list item 1</item>
        <item>list item 2</item>
        <item special='yes'>list item 3</item>
    </key2>
    <mappingseries>
        <mapping>
            <cola special='yes'>a</cola>
            <colb>b</colb>
            <colc>c</colc>
        </mapping>
        <mapping>
            <cola>A</cola>
            <colb special='yes'>B</colb>
            <colc>C</colc>
        </mapping>
    </mappingseries>
</sample>

Template File

.. -*- mode: rst -*-

Static Heading
--------------

Individual Item
~~~~~~~~~~~~~~~

{{ data.find('key1').text }}

List of Items
~~~~~~~~~~~~~

{% for item in data.find('key2') %}
- {{item.text}}
{% endfor %}

XPath for Items
~~~~~~~~~~~~~~~

See `XPath support <https://docs.python.org/3/library/xml.etree.elementtree.html#xpath-support>`_

{% for item in data.findall(".//*[@special='yes']") %}
- {{item.text}}
{% endfor %}

Rendered Output

Static Heading

Individual Item

value1

List of Items
  • list item 1
  • list item 2
  • list item 3
XPath for Items

See XPath support

  • list item 3
  • a
  • B

Legacy Samples

The datatemplate directive is should no longer be used. It is deprecated, and will be removed in the next release.

Data File

---
key1: value1
key2:
  - list item 1
  - list item 2
  - list item 3
nested-list:
  - ['a', 'b', 'c']
  - ['A', 'B', 'C']
mapping-series:
  - cola: a
    colb: b
    colc: c
  - cola: A
    colb: B
    colc: C

Template File

.. -*- mode: rst -*-

Static Heading
--------------

Individual Item
~~~~~~~~~~~~~~~

{{ data['key1'] }}

List of Items
~~~~~~~~~~~~~

{% for item in data['key2'] %}
- {{item}}
{% endfor %}

Nested List Table
~~~~~~~~~~~~~~~~~

Rendering a table from a list of nested sequences using hard-coded
headers.

{{ make_list_table(
    ['One', 'Two', 'Three'],
    data['nested-list'],
    title='Table from nested lists',
    ) }}

Mapping Series Table
~~~~~~~~~~~~~~~~~~~~

Rendering a table from a list of nested dictionaries using dynamic
headers.

{{ make_list_table_from_mappings(
    [('One', 'cola'), ('Two', 'colb'), ('Three', 'colc')],
    data['mapping-series'],
    title='Table from series of mappings',
    ) }}

Rendered Output

Static Heading

Individual Item

value1

List of Items
  • list item 1
  • list item 2
  • list item 3
Nested List Table

Rendering a table from a list of nested sequences using hard-coded headers.

Table from nested lists
One Two Three
a b c
A B C
Mapping Series Table

Rendering a table from a list of nested dictionaries using dynamic headers.

Table from series of mappings
One Two Three
a b c
A B C

Indices and tables