28

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?

Community
  • 1
  • 1
Bud P. Bruegger
  • 1,021
  • 10
  • 15

2 Answers2

34

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]

Adam Johnson
  • 471
  • 1
  • 5
  • 11
Bud P. Bruegger
  • 1,021
  • 10
  • 15
  • 3
    This is brilliant. I not only added `rst_prolog = open('global.rst', 'r').read()` to "conf.py", but I added "global.rst" to `exclude_patterns`: exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.git', 'global.rst'] to keep it from being processed - otherwise Sphinx generates warnings about duplicate definitions. – Doug Cuthbertson May 21 '18 at 10:30
7

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.

Næreen
  • 1,126
  • 1
  • 12
  • 23
Chris
  • 44,602
  • 16
  • 137
  • 156