python-sphinx - 如何在 Sphinx 中创建全局角色/角色？

Question

这是“ReST 删除线”的后续 ReST strikethrough但在 Sphinx 而不是 ReST 上下文中。我的问题是 sphinx 中是否有一个中心位置可以放置“角色”指令，或者该指令是否真的必须在 sphinx 文档中的每个 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 文件中重复角色指令。是否有一个“中央”地方可以为整个站点定义一次？

Answer 1

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

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

另请注意，出于我的目的，没有类属性的角色指令工作正常。

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