sphinxcontrib-datatemplates

0.11.0 verified Fri May 01 auth: no python

A Sphinx extension that renders data files (YAML, JSON, CSV, etc.) as nicely formatted HTML tables or custom templates. Current version 0.11.0, requires Python >=3.8, released periodically.

pip install sphinxcontrib-datatemplates

Common errors

error Extension error: Could not import extension sphinxcontrib.datatemplates ↓

cause Missing package or misspelled extension name in conf.py.

fix

Install with 'pip install sphinxcontrib-datatemplates' and check ext_list: ['sphinxcontrib.datatemplates'] (dot, not underscore).

error Directive 'datatemplate' is not registered ↓

cause Sphinx does not recognize the directive; extension possibly not loaded.

fix

Ensure 'sphinxcontrib.datatemplates' is in extensions list in conf.py and that you are using the correct directive name (not 'data').

error Template 'table.rst.j2' not found ↓

cause The specified Jinja2 template path is incorrect or missing.

fix

Place template in source directory or provide absolute/relative path from conf.py directory.

Warnings

breaking Version 0.6.0 renamed the directive from 'data' to 'datatemplate'. Old syntax using '.. data::' breaks; update to '.. datatemplate::'. ↓

fix Replace '.. data::' with '.. datatemplate::' in all .rst files.

gotcha The extension does not automatically reload data files on each build; changes require a clean build. Use 'make clean' before rebuilding. ↓

fix Run 'make clean' after modifying data files, or use sphinx-autobuild.

deprecated Support for CSV files may be removed in a future version; prefer JSON or YAML. ↓

fix Convert CSV data to JSON or YAML format.

Imports

setup

wrong

from sphinxcontrib_datatemplates import setup

correct

from sphinxcontrib.datatemplates import setup

Common mistake: using underscore instead of dot in the module path

Quickstart

Activate the extension in conf.py, then use the datatemplate directive in reStructuredText to include data files rendered via Jinja2 templates.

# conf.py
import os
extensions = ['sphinxcontrib.datatemplates']
# In any .rst file:
# .. datatemplate:: path/to/data.yaml
#    :template: table.rst.j2