python - 全局包含在重组文本中

Question

我正在为我的博客/网站使用 reStructuredText，并且我想添加一个全局包含文件。我可以访问并很高兴更改用于生成 html 输出的设置文件，但我只是无法弄清楚其中任一的语法:

1. 向解析器添加默认包含文件
2. 使用 python 中的 docutils 在 python 中定义指令/内联角色等

我尝试阅读源代码和文档，但发现它有点难以理解。我希望我只是错过了一些非常明显的东西，但我想做类似以下的事情(第一部分就是已经存在的东西 - 你可以看到 rest of the file in the jekyll-rst plugin source (links right to it)

import sys
from docutils.core import publish_parts
from optparse import OptionParser
from docutils.frontend import OptionParser as DocutilsOptionParser
from docutils.parsers.rst import Parser

# sets up a writer that is then called to parse rst pages repeatedly
def transform(writer=None, part=None):
    p = OptionParser(add_help_option=False)

    # Collect all the command line options
    docutils_parser = DocutilsOptionParser(components=(writer, Parser()))
    for group in docutils_parser.option_groups:
        p.add_option_group(group.title, None).add_options(group.option_list)

    p.add_option('--part', default=part)

    opts, args = p.parse_args()


# ... more settings, etc

# then I just tell the parser/writer to process specified file X.rst every time
# (or alternately a python file defining more roles...but nicer if in rst)

有没有简单的方法可以做到这一点？如果定义一个文件 defaults.rst 并每次都加载该文件，那就太好了。

编辑:以下是我希望能够全局包含的一些示例(自定义指令也很好，但我可能会用代码编写它们)

.. role:: raw-html(raw)
   :format: html

.. |common-substitution| replace:: apples and orange

.. |another common substitution| replace:: etc

Answer 1

我不太确定我是否理解这个问题。例如，您是否想要在某个文件中定义多个替换，并让这些替换在您的所有其他 reStructuredText 文件中可用，或者您是否希望在输出文件中包含一些常见的 HTML？你能澄清一下你的问题吗？

如果您想要前者，您可以使用 include指令，正如我在 this answer 中概述的那样.

或者，如果您希望在生成的输出中包含一些常见的 HTML，请尝试复制并编辑模块 path/to/docutils/writers/中包含的 template.txt 文件html4css1/.您可以在此文件中包含任意 HTML 元素并修改 Docutils 生成的 HTML 的布局。这两种方法都不需要您修改 Docuitls 源代码，这始终是一个优点。

编辑:我认为不可能设置一个标志来使用 Docuitls 设置包含文件。但是，如果您可以使用 Sphinx ，它基于 Docuitls 但有大量扩展，那么这个包有一个设置 rst_prolog这正是您所需要的(请参阅 this answer )。 rst_prolog 是:

A string of reStructuredText that will be included at the beginning of every source file that is read.