sphinxcontrib.datatemplates

What it is and what it does

sphinxcontrib-datatemplates is a Sphinx extension that bridges external data files and documentation by rendering reStructuredText content from JSON, YAML, and CSV sources using Jinja2-style templating. Instead of hardcoding data into your documentation, you maintain it separately and reference it via template directives—useful when documentation needs to reflect live configuration, API schemas, or tabular data that changes independently of the docs themselves.

The extension provides template functions like `make_list_table` and `make_list_table_from_mappings` to convert nested data structures into reStructuredText tables. It depends on Sphinx, PyYAML, defusedxml (for safe XML parsing), and sphinxcontrib-runcmd. The package is in Beta status, last released in late 2023, and supports Python 3.8 through 3.12.

Use it for:

• Render API endpoint documentation from a YAML schema file that is version-controlled separately from docs.
• Generate configuration reference tables from JSON files that are auto-generated by your build system.
• Build comparison matrices or feature tables from CSV data without manually editing reStructuredText.
• Keep deployment or environment documentation synchronized with YAML configuration files.
• Create dynamic release notes or changelog tables from structured data sources.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Sphinx extension that renders reStructuredText documentation content from external data files (JSON, YAML, CSV) using templating, allowing you to keep data separate from documentation source.

Yes, if you use Sphinx and need to keep documentation content synchronized with external data files. The low install friction and permissive license make it a straightforward addition. However, the aging maintenance status (last release 2023-12-21, 967 days old) means you should verify compatibility with your Sphinx version and be prepared to maintain a fork if critical issues arise.

Install

sphinxcontrib-datatemplates on PyPI

pip install sphinxcontrib-datatemplates

uv add sphinxcontrib-datatemplates

poetry add sphinxcontrib-datatemplates

Installing sphinxcontrib.datatemplates

Before you install

Low friction install with four runtime dependencies (Sphinx, PyYAML, defusedxml, sphinxcontrib-runcmd). Maintenance is aging—last release was 2023-12-21 and the repository has not been archived, but activity has slowed significantly.

License in practice

Permissive BSD license; no restrictions on use, modification, or distribution in commercial or private projects.

Quickstart

pip install sphinxcontrib-datatemplates

# In conf.py:
extensions = ['sphinxcontrib.datatemplates']

# In a .rst file:
.. datatemplate:yaml:file: data.yaml

   Individual Item: {{ data['key1'] }}
   List: {% for item in data['key2'] %}- {{item}}{% endfor %}

Requires Sphinx to be installed and configured; data files must be in a supported format (JSON, YAML, or CSV) and accessible to the Sphinx build process.

Verify before relying

• Whether the package supports CSV templating with the same feature set as YAML and JSON.
• Performance characteristics when rendering large data files or complex nested structures.
• Compatibility with recent Sphinx versions beyond 3.12 classifier coverage.

Package facts

Evidence: sphinxcontrib.datatemplates-0.11.0-py3-none-any.whl

Tags

More Utilities packages