docutils/reStructuredText 模板功能

Question

如何使用实际值自定义 .rst 文件中的占位符？

例如，我有 example.rst 文件，内容如下：

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

我想通过运行以下命令将 ${custom_text} 属性替换为值 this is the value of custom property：

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

我也想知道是否可以使用.properties 文件自定义模板？例如，我想使用example.properties 文件运行rst2html example.rst -o example.html -p example.properties 命令，其内容如下：

custom_text=this is the value of custom property

有可能吗？ reStructuredText 是否完全支持模板功能？

编辑：请注意，我想从命令行自定义模板或使用常规的.properties 文件（可由 Ant/Maven 构建管理工具使用）。

Answer 1

有几个处理模板的选项：

a) 使用内部替换机制：

模板.txt::

 Header
 ======

 |custom text|

example.txt::

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

转换为rst2html example.txt -o example.html。

这样您就可以处理内联文本和图像。

b) 编写您自己的包装器：一个 Python 脚本，它读取 template 和 properties 文件，进行替换，并使用 Docutils.core 中的一个函数进行转换。

Answer 2

reStructuredText 文件中的替换是使用replace 指令执行的。例如：

I am using |RST|.

.. |RST| replace:: reStructuredText

会产生文字

我正在使用 reStructuredText。

您可以使用include 指令在单独的文件中定义替换模板列表。例如，给定以下两个文件：

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"

将生成文档：

标题

我可以包含来自其他文件的文本，例如“示例文本”。

这里我使用了命令rst2html.py example.rst 来生成HTML 输出。