Sphinx 文档变量

Question

我正在使用Sphinx为新项目编写文档

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

所以我想知道是否有办法在Sphinx上放置一些变量/常量来做到这一点。

我知道Sphinx上有一个i18n功能，所以我可以使用 gettext 来更改“项目名称”而无需其他任何内容。 但我正在寻找一种正确的方法来做到这一点。

Answer 1

sphinx使用配置值引用项目名称。 如果您使用sphinx-quickstart创建 xyour sphinx项目，则会询问您的项目名称。 您可以通过更改之后更改项目名称project在conf.py

您可以在.rst文件中使用配置值，方法是在conf.py使用rst_epilog定义它们（请参阅此答案以获取示例）。

Answer 2

从狮身人面像文档：

reST 支持“替换”（ ref ），它们是文本片段和/或文本中由|name|引用的标记|name| . 它们的定义类似于带有显式标记块的脚注，如下所示：

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

或这个：

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

有关替换的详细信息，请参阅reST 参考。

如果您想对所有文档使用某些替换，请将它们放入rst_prolog或rst_epilog或将它们放入单独的文件中，并使用include指令将其include到您想要使用它们的所有文档中。 （一定要给包含文件一个不同于其他源文件的文件扩展名，以避免 Sphinx 发现它是一个独立的文档。）

在rst_prolog添加您的“项目变量”并使用替换。