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

Question

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

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

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