Menu
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?
665
The any role also works together with the intersphinx extension: when no local cross-reference is found, all object types of intersphinx inventories are also searched. To support cross-referencing to arbitrary locations in any document, the standard reST labels are used.
This directory also contains the Sphinx configuration file conf.py, where you can configure all aspects of how Sphinx reads your sources and builds your documentation. 1
In Sphinx source files, you can use most features of standard reStructuredText. There are also several features added by Sphinx. For example, you can add cross-file references in a portable way (which works for all output types) using the ref role.
A build is started with the sphinx-build program: where sourcedir is the source directory, and builddir is the directory in which you want to place the built documentation. The -b option selects a builder; in this example Sphinx will build HTML files. Refer to the sphinx-build man page for all options that sphinx-build supports.
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]
95
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With