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

本文介绍了如何在 Sphinx 中创建全局角色/角色?的处理方法，对大家解决问题具有一定的参考价值，需要的朋友们下面随着小编来一起学习吧！ 问题描述

这是ReST 删除线"ReST 删除线 的后续，但在 Sphinx 而非 ReST 上下文中.我的问题是 sphinx 中是否有一个中心位置可以放置角色"指令，或者该指令是否真的必须在 sphinx 文档中的每个 rst 文件中重复.

This is a followup of "ReST Strikethrough" ReST strikethrough but in a Sphinx rather than ReST context. My question is whether there is a central place in sphinx where to put a "role" directive or whether this directive really has to be repeated in every rst file within a sphinx docmentation.

更详细:

使用角色指令很容易为内联文本定义自定义 CSS 样式(参见 ReST 删除线示例):

It is easy to define custom CSS styles for inline text (see ReST Strikethrough as example) using a role directive:

.. role:: custom :class: custom This is an :custom:`inline text`.

翻译成

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

此外，自定义样式表可以轻松添加到 sphinx(参见 www.tinkerer.me/doc/theming.html) 在哪里添加 CSS 类选择器来控制自定义"文本的呈现方式(颜色、删除线、字体、大小...)

Also, a custom stylesheet can easily be added to sphinx (see www.tinkerer.me/doc/theming.html) where to add a CSS class selector to control how "custom" text is rendered (color, strikethrough, font, size...)

令我不安的是，在我的实验中，我不得不在每个使用自定义角色的 ReST 文件中重复角色指令.是否有一个中央"位置可以为整个站点定义一次?

What disturbes me is that in my experiments, I had to repeat the role directive in every ReST file that used the custom role. Is there a "central" place where I can define this once for the whole site?

推荐答案

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

It seems that rst_prolog that is set in the conf.py file is the central place that I was looking for. Rst_prolog is "A string of reStructuredText that will be included at the beginning of every source file that is read". In my case, I simply added the following to conf.py:

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

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

Note also that for my purpose, the role directive without a class attibute works just fine.

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

Obviously, as Chris has pointed out, an rst_prolog that accomplishes many things could be achieved by including a global.rst file. [There may be issues with its relative path, however. Maybe better to use rst_prolog = open('global.rst', 'r').read() --untested]