Sphinx Role

Using a combination of information from Sphinx substitutions and Stackoverflow, we can create a custom section for part of our text. This only works for one instance, which can be used as often as you like.

Sphinx Setup

Assuming we have a modern Sphinx layout, but it also works on the older layout:

Application
   ├──docs
   │     ├──build
   │     ├──source
   │     │     ├──_static
   │     │     │     ├──css
   │     │     │     └──fonts
   │     │     ├──_templates
   │     │     ├──app files
   │     │     ├──conf.py
   │     │     └──index-rst
   │     │
   │     ├──make.bat
   │     └──Makefile
   │
   └──README.md

This shows a simplified modern layout - we are mostly involved in the source folder - use the css folder to store our scripts and the fonts folder to store custom fonts. conf.py is the central file where any changes to the configuration and methods are made.

Customising Parts of Sphinx

Normally all the fonts and sizes are handled by the sphinx theme. Each part of sphinx is covered and we have no normal methods to change a part of the text apart from standard sphinx methods - in our case using rst.

This method allows us to use a font using standard css rules within our custom style file, custom.css found within the css folder:

@font-face {
  font-family: "Kingofthieves";
  src: url((../fonts/Kingofthieves-v6mL.ttf);
}

The font was in the fonts folder and required the relative path between the folders css and fonts. This font is now available to custom.css. Now add our instructions on how it should be rendered:

.keys {
   font-family: "Kingofthieves";
   font-size: 60px;
   color: #ff073a;
   text-shadow: 0 0 3px #ccff02;
}

We are using a class keys preceded with a full stop. In this case we want to use our custom font, with its size, color and text shadow.

Now to make it work conf.py must be configured. Ensure that the following two lines exist in conf.py:

html_static_path = ['_static']
html_css_files = ['css/custom.css']

All this does is tell conf.py where to find our custom style file and its name. Now to tell conf.py what to do:

rst_prolog = f"""
.. role:: AL
   :class: keys
"""

We have added an rst role called AL and it will use the input from our custom class keys, which conf.py knows is in our custom script. All we have to do is call up AL together with the text that requires altering:

:AL:`Frothy Brew`

Our text is enclosed in single backward pointing inverted commas.

Unfortunately as there is only one rst_prolog role we are limited in our actions. To see this in action Some of the trickier parts of tkinter.ttk.