Sphinx文档变量

Question

我正在为一个新项目写文档，使用的是Sphinx这个工具。

但是因为这个项目是新的，它的名字可能会改变，我不想在所有文档中都去替换“项目名称”的所有引用。

所以我想知道有没有办法在Sphinx中放一个变量或常量来解决这个问题。

我知道Sphinx有一个i18n功能，可以用gettext来改变“项目名称”，这样就不用做其他的修改。但我想找一个更合适的方法来实现这个。

Answer 1

来自Sphinx文档的内容：

reST支持“替换”（参考），这是一种可以在文本中用|name|来引用的文本或标记。它们的定义方式类似于脚注，使用明确的标记块，像这样：

.. |name| replace:: replacement *text*

或者这样：

.. |caution| image:: warning.png
         :alt: Warning!

想了解更多细节，可以查看reST替换的参考文档。

如果你想在所有文档中使用某些替换，可以把它们放在rst_prolog或rst_epilog中，或者把它们放在一个单独的文件里，然后通过include指令把这个文件包含到你想使用的所有文档中。（确保给包含文件一个不同于其他源文件的文件名后缀，以避免Sphinx把它当作独立文档来处理。）

在rst_prolog中添加你的“项目变量”，然后使用替换。

Answer 2

项目名称是通过 sphinx 的配置值来引用的。如果你使用 sphinx-quickstart 来创建你的 sphinx 项目，它会询问你项目的名称。你可以在之后通过修改 conf.py 文件中的 project 来更改项目名称。

你可以在 .rst 文件中使用配置值，只需在 conf.py 文件中用 rst_epilog 定义它们即可（具体例子可以参考 这个回答）。