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

Question

这是"ReST Strikethrough" ReST删除的后续行动,但是在Sphinx而不是ReST背景下.我的问题是,在sphinx中是否有一个中心位置放置一个"角色"指令,或者这个指令是否真的必须在sphinx docmentation中的每个第一个文件中重复.

更详细:

使用角色指令很容易为内联文本定义自定义CSS样式(请参阅ReST Strikethrough作为示例):

.. 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]

Answer 2

从使用sphinx记录项目的示例中,您可以使用include将global.rst包含所有角色指令的文件替换为其他文件.从这个网站:

语法:

.. include:: myfile.rst

将"内联"给定文件(myfile.rst).我使用的一个常见约定是创建一个名为的全局.rst文件,global.rst并将其包含在每个页面的顶部.对于常见图像或公共文件链接等的链接非常有用.