Sphinx docs变量

Question

我正在编写一个新项目的文档 Sphinx

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

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

我知道有一个i18n功能Sphinx,所以我可以使用gettext更改"项目名称"而不需要其他任何东西.但我正在寻找一种正确的方法来做到这一点.

Answer 1

sphinx使用配置值引用项目名称.系统会询问您是否使用sphinx-quickstart创建xyour sphinx项目的项目名称.您可以通过更改project您的项目来更改项目名称conf.py

您可以使用您的配置值.rst在定义它们的文件conf.py用rst_epilog(见这个答案的例子).

Answer 2

从Sphinx文档中：

reST支持“替换”（ref），它是文本中所引用的文本和/或标记|name|。它们的定义就像带有显式标记块的脚注一样，如下所示：

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

或这个：

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

有关替代的详细信息，请参见reST参考。

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

在其中添加“项目变量” rst_prolog并使用替代。