Generate rst files per data file

[danwos]

First of all, thanks for this great extension.

I'm searching for a way to generate the rst-files based on data files I have. So for each data file, I would like to get automatically a rst file, which uses .. datatemplate:: to combine the data with a given template.

Benefit: I do not need to create rst-files. A new data file is enough to get it to the documentation.

Is that feature something, datatemplates is allowed to provide? Or is it maybe out of scope?

I maybe find some time to help with the realisation. But no promises, you know, christmas/new year chaos :)

This is also related to https://github.com/sphinx-contrib/datatemplates/issues/4.

Technical realisation proposal

In conf.py a config parameter is needed:

datatemplates_imports = [{
  'path: 'data/my_users/', 
  'template': 'my_template', 
  'target': 'my_content/'  ,
  'csvheader': 'optional',
  'csvdialect': 'optional' },
  {...}
]

Then for each data-file in path, a rst-file is generated inside target, where the file name is the data-file-name + ".rst".

The generated rst-files have a single, configured .. datatemplate:: in it, so that the further build process keeps as it is: E.g. my_content/petra.rst

.. datatemplate::
   :source: data/my_users/petra.json
   :template: my-template
   :csvheader: if given
   :csvdialect: if given

The user can then reference to the data for instance like this:

.. toctree::
   :glob:

   my_content/*

After the build process, the target folder should be cleaned, so that the rst-files get regenerated with each new build and nobody tries to modify them directly (may be deactivated via config).

[dhellmann]

This is an interesting idea, and I'm sure it comes up in a lot of contexts independently from using data templates. It might be best to approach this by designing a system for creating the pages from their own templates, and then simply use data templates features with that separate extension.

The documentation about sphinx build phases and core events might be useful.

I don't immediately see a way to make Sphinx invoke your code at the right point, when enough of the engine is initialized to be useful but the input files haven't been read. I know of other systems that have tapped into setuptools or other build systems to dynamically create pages before invoking Sphinx.

[janbrohl]

You could invoke the not-yet-documented ( #3 ) and currently not well mainatined CLI for this by calling it in eg. in the makefile. Try python -m sphinxcontrib.datatemplates.cli --help for more info.