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

Question

这是"ReST Strikethrough"的后续问题（ReST中删除线），但是这次问题是在Sphinx而不是在ReST环境下。我的问题是是否有一个中心位置可以放置“role”指令，或者是否必须在每个Sphinx文档中的rst文件中重复该指令。更具体地说，使用role指令很容易为内联文本定义自定义CSS样式（例如请参见ReST Strikethrough），但我想知道是否有一种方法可以在Sphinx文档中的所有rst文件中共享它们。

.. 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文件中重复使用role指令。 是否有一个“中央”位置，我可以在整个站点上定义这个角色一次？

- Bud P. Bruegger

---

更新的Tinkerer链接：http://www.tinkerer.me/doc/more_tinkering.html#theming - stratosgear

我在这里添加了一些解释：https://dev59.com/uGUq5IYBdhLWcg3wSehm#24932178 - Rolf

Answer 1

看起来，我一直在寻找的中心位置是在conf.py文件中设置的rst_prolog。Rst_prolog是“将包含在读取的每个源文件开头的reStructuredText字符串”。在我的情况下，我只需将以下内容添加到conf.py中：

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

请注意，对于我的目的，没有class属性的role指令就足够了。

显然，正如Chris所指出的那样，通过包含一个global.rst文件，可以实现许多功能的rst_prolog。但是，它的相对路径可能存在问题。也许最好使用rst_prolog = open('global.rst', 'r').read() --未经测试。

- Bud P. Bruegger

---

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

Answer 2

从使用sphinx记录项目文档的示例中，您可以使用include将包含所有角色指令的global.rst文件替换为其他文件。来自此网站：

The syntax:

.. include:: myfile.rst

Will "inline" the given file (myfile.rst). A common convention I use is create a global .rst file called global.rst and include that at the top of every page. Very useful for links to common images or common files links, etc.

- Chris

---

我相信这是 .. include:: myfile.rst。 - Rolf