docutils/reStructuredText template features

Question

How could I customize placeholders in my .rst file with actual values?

For example, I have example.rst file with following content:

Header
------------------------------------ 
${custom_text}

I want to replace ${custom_text} property with the value this is the value of custom property by running following command:

rst2html example.rst -o example.html -Dcustom_text="this is the value of custom property"

Also I wonder whether it is possible to customize template using .properties file? For example, I would like to run rst2html example.rst -o example.html -p example.properties command using example.properties file with following content:

custom_text=this is the value of custom property

Is it possible? Does reStructuredText support template features at all?

EDIT: Please note that I want to customize template from command line or using conventional .properties file (can be used by Ant/Maven build management tool).

Answer 1

Substitution in reStructuredText files is performed using the replace directive. For example:

I am using |RST|.

.. |RST| replace:: reStructuredText

will result in the text

I am using reStructuredText.

You could use the include directive to define a list of substitution templates in a separate file. For example, given the following two files:

example.rst:

Header
======

.. Include templates from external file (this is a comment).
.. include:: properties.rst

I can include text, like |my custom text|, from other files.

properties.rst

.. |my custom text| replace:: "example text"

will result in the document:

Header

I can include text, like "example text", from other files.

Here I have used the command rst2html.py example.rst to generate the HTML output.

Answer 2

There are several options to handle templating:

a) use the internal substitution mechanism:

template.txt::

 Header
 ======

 |custom text|

example.txt::

 .. |custom text| replace:: this is the value of custom property

convert with rst2html example.txt -o example.html.

This way you can handle inline text and images.

b) Write your own wrapper: a Python script that reads template and properties files, does the replacements, and convert with one of the function in Docutils.core.