python-sphinx - Sphinx 内联包括

Question

我想使用内联的 .. include:: 函数，但是如果我用两行新行将它与前面的文本分开，我只能让它实际包含我想要的文件。

在有人问之前，我想包含的文件是一个协议(protocol)号，所以不，它根本不会从新行中受益。我希望能够轻松更改它，以便我可以在文档的多个位置使用它。我想一个例子是“我们当前使用协议(protocol)(proto.txt)”。我是 Sphinx 的新手，所以也许我还没有找到一个非常明显的解决方案。

Answer 1

Sphinx 无法进行内联包含。

但是，您可以定义全局 aliases (替换)在 build configuration file 的 rst_epilog 变量中.

例如，您可以将以下行添加到 conf.py 文件中:

rst_epilog = """
  .. |version| replace:: 4.1
  .. |protocol| replace:: httpx
"""

现在，您可以从项目中的任何 .rst 文件访问变量 |version| 和 |protocol|，例如如下所示:

版本 |版本|使用|协议(protocol)|协议(protocol)。

变成了

4.1版本使用httpx协议(protocol)。

如果软件的其他部分需要以特定文件或格式指定协议(protocol)(或其他变量)，您可以编写一个脚本以将其作为变量读取到 Sphinx 配置中文件。