0

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).

altern
  • 5,829
  • 5
  • 44
  • 72

2 Answers2

10

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.

Jeff Tratner
  • 16,270
  • 4
  • 47
  • 67
Chris
  • 44,602
  • 16
  • 137
  • 156
  • You gave great answer about templating feature of reStructuredText. I need to admit that I didn't know about templating capabilities of reStructuredText even though I supposed there should be some way. But still, I'm afraid that's not going to solve my problem - I want to customize template from command line or using conventional `.properties` file (can be used by Ant/Maven build management tool) – altern Mar 20 '12 at 16:56
  • 1
    You are going to have to write these things yourself. Since rst2html.py does not have a `-p` or `-D` option you'll need some sort of wrapper script. The `-D` behaviour can be achieved by running your reStructuredText file through, for example, the C language preprocessor. I'll have a think about the properties file when I have a bit more time. However, you are wanting to use reStructuredText in a way that it isn't designed to be used, which may be more trouble than it is worth. – Chris Mar 20 '12 at 18:14
  • Ok, I see. It seems that you're right - I should use another format. – altern Mar 20 '12 at 18:35
  • Is there any way to use the replace directive for *multiline* replacements? I cannot get it to do so. – mareoraft Jul 11 '18 at 02:41
0

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.

G. Milde
  • 66
  • 3