---
id: sphinxcontrib-datatemplates
version: "0.11.0"
license: unclear
license_treatment: permissive
maintenance: aging
---

# sphinxcontrib.datatemplates — Sphinx extension for rendering data files as nice HTML

License: permissive · Maintenance: aging · Downloads: 125.5K/mo

## 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 above — 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

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

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 125.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx data templating, render documentation from yaml, sphinx json data files, dynamic documentation generation, sphinx csv table rendering, data-driven sphinx docs, sphinx external data source, sphinx-extension, data-driven-docs, templating

[View on SkillFed](https://skillfed.io/packages/sphinxcontrib-datatemplates) · [View on PyPI](https://pypi.org/project/sphinxcontrib-datatemplates/)