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 calledglobal.rst
and include that at the top of every page. Very useful for links to common images or common files links, etc.