python - Sphinx 文档变量

Question

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

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

所以我想知道是否有办法把一些变量/常数放在上面Sphinx。

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

Answer 1

通过sphinx使用配置值来引用项目名称。询问您的项目名称是否sphinx-quickstart用于创建 xyoursphinx项目。之后您可以通过更改project您的项目名称来更改项目名称conf.py

您可以通过在.rst文件中定义它们来conf.py使用文件中的配置值（有关示例，rst_epilog请参见此答案）。

Answer 2

从狮身人面像文档：

reST 支持“替换”（ref），它是由|name|. 它们被定义为带有显式标记块的脚注，如下所示：

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

或这个：

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

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

如果您想对所有文档使用一些替换，请将它们放入rst_prolog或rst_epilog或将它们放入单独的文件中，并将其包含到您要使用它们的所有文档中，使用include指令。（确保为包含文件提供与其他源文件不同的文件扩展名，以避免 Sphinx 将其视为独立文档。）

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