如何在 Sphinx 中创建全局角色/角色？答案

【问题标题】：How do I create a global role/roles in Sphinx?如何在 Sphinx 中创建全局角色/角色？
【发布时间】：2012-03-14 09:04:33
【问题描述】：

这是“ReST 删除线”ReST strikethrough 的后续，但在 Sphinx 而不是 ReST 上下文中。我的问题是狮身人面像中是否有一个中心位置可以放置“角色”指令，或者该指令是否真的必须在狮身人面像文档中的每个 rst 文件中重复。

更详细的：

使用角色指令很容易为内联文本定义自定义 CSS 样式（请参阅 ReST 删除线作为示例）：

.. role:: custom
   :class: custom

This is an :custom:`inline text`.

翻译成html渲染的

.. This is an <span class="custom">inline text</span>.  ..

此外，自定义样式表可以轻松添加到 sphinx（请参阅 http://www.tinkerer.me/doc/theming.html），在其中添加 CSS 类选择器以控制“自定义”文本的呈现方式（颜色、删除线、字体、大小...）

令我不安的是，在我的实验中，我不得不在每个使用自定义角色的 ReST 文件中重复角色指令。是否有一个“中心”位置，我可以为整个网站定义一次？

【问题讨论】：

【解决方案1】：

似乎在 conf.py 文件中设置的rst_prolog 是我正在寻找的中心位置。 Rst_prolog 是“将包含在每个读取的源文件开头的 reStructuredText 字符串”。就我而言，我只是在 conf.py 中添加了以下内容：

rst_prolog = """
.. role:: test2
"""

还要注意，出于我的目的，没有类属性的 role 指令可以正常工作。

显然，正如 Chris 所指出的，一个完成许多事情的 rst_prolog 可以通过包含一个 global.rst 文件来实现。 [但是，它的相对路径可能存在问题。最好使用 rst_prolog = open('global.rst', 'r').read() --untested]

【讨论】：

这太棒了。我不仅在“conf.py”中添加了rst_prolog = open('global.rst', 'r').read()，还在exclude_patterns中添加了“global.rst”：exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.git', 'global.rst'] 以防止其被处理 - 否则 Sphinx 会生成有关重复定义的警告。

【解决方案2】：

从documenting your project using sphinx 的示例中，您可以使用include 将包含所有角色指令的global.rst 文件替换到其他文件中。从这个网站：

语法：
.. include:: myfile.rst
将“内联”给定文件 (myfile.rst)。我使用的一个常见约定是创建一个名为 global.rst 的全局 .rst 文件，并将其包含在每一页的顶部。对于常用图片链接或常用文件链接等非常有用。

【讨论】：