How do I create a global role/roles in Sphinx?

问题:

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.

In more detail:

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

which translates into a html rendering of

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

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

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?

回答1:

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
"""

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

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]

回答2:

From the example at documenting your project using sphinx, you can use include to substitute a global.rst file, which contains all your role directives, into your other files. From this site:

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.