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

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]


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.