sphinx, restructuredtext: set color for a single word
Solution 1
If you want to do this without being tied to html, try applying a different style than normal body text to your word.
In this example adapted from the rst2pdf manual, I apply the existing rubric style which is red in the backend that I am using:
Before red.
.. role:: rubric
I like color :rubric:`rubric`.
After red.
The actual look of the word will depend on how the style you choose is defined in the stylesheet that you use when generating your document. If you want blue text, make a blue text style and derive it from the normal text style. The stylsheet is backend-specific and you may be using the default. To print the default for rst2pdf.py, do this (from the rst2pdf manual):
rst2pdf --print-stylesheet
Continuing the example for a rst2pdf stylesheet, add this to your stylesheet to have a blue text style:
bluetext:
parent: bodytext
textColor: blue
In the document you can reference this style to get a blue word. Note this bit is generic, and should make blue text if you define a blue style in your html or whatever backend's stylesheet.
Before blue.
.. role:: bluetext
I like color :bluetext:`blue`.
After blue.
The generated pdf has the coloured words:
Solution 2
On my Sphinx-powered website, I use a combination of:
- A restructuredText file containing roles definitions, one for each color - see .special.rst (BitBucket link)
- A CSS file containing color rules for each role - see the first lines of hacks.css (BitBucket link)
Then, in every rST file where I need colors, I first import .special.rst
at the top, either manually:
.. include:: .special.rst
Or with the rst_epilog
configuration variable in Sphinx's conf.py
file:
rst_epilog = "\n.. include:: .special.rst\n"
And then each role can be used easily in pure rST syntax:
This is :red:`red !` And :blue:`this part is blue`.
More details are given on this page (in French, sorry).
It works perfectly well for html output (and html-like), but not for PDF. Refer to the first answer above for producing a PDF with colors.
Solution 3
Sphinx already supports colors with the s5defs.txt
standard definition file intended for inclusion (but is missing the CSS file):
-
Create/append this text to the value of
rst_epilog
sphinx configuration, in yourdocs/conf.py
file:rst_prolog = """ .. include:: <s5defs.txt> """
-
Follow Sphinx's instructions to add a css with the colors (e.g. adopt the
hack.css
from @Næreen's answer):
-
Place your css file into e.g.
_static/css/s4defs-roles.css
; -
append it's path into
shtml_css_files
sphinx configuration:html_css_files = ['css/s4defs-roles.css']
You may then use:
Some :red:`colored text` at last!
TIP: Read this SO if you also want the styling to appear in Latex output.
Solution 4
This works, but leaves the HTML in a separate paragraph.
.. raw:: html
<font color="blue">Blue word,</font>
And a word without color
If anyone has a better answer, I will accept it.
Solution 5
Just a quick note because I landed here looking for something similar for html
.
This works on Sphinx v2.0.1 for me. This uses the concept reported by @adam-matan but doesn't cause any formatting issues (i.e. the paragraph problem).
reference: reStructuredText Directives
.. role:: raw-html(raw)
:format: html
:raw-html:`<font color="blue">Blue word,</font>` And a word without color
Related videos on Youtube
![Adam Matan](https://i.stack.imgur.com/QG9pG.jpg?s=256&g=1)
Adam Matan
Team leader, developer, and public speaker. I build end-to-end apps using modern cloud infrastructure, especially serverless tools. My current position is R&D Manager at Corvid by Wix.com, a serverless platform for rapid web app generation. My CV and contact details are available on my Github README.
Updated on August 10, 2020Comments
-
Adam Matan almost 4 years
Is there a way to set the color of single words (or characters) in sphinx? I'm pretty sure there should be some markup tag, like HTML's
font
tag. -
umbe1987 over 6 yearsI like this solution!
-
YOUNG over 6 yearsThanks for this solution. It works but do you know how to solve
WARNING: Problems with "include" directive path:
? I don't know how to specify that.special.rst
to be at project root directory inconf.py
. I tried/
and~/
but neither works. -
Næreen over 6 yearsI don't know, in my case the
conf.py
file and all therst
files are in the same folder, so there is no need to specify anything. -
umbe1987 over 5 yearsAfter one year (see my first comment ;)) this solution is still great, although I have noticed (at least from my side), that after the first succesful build with
make html
, the following attempts to build with the same command always end up with (e.g. for red color)WARNING: Unknown interpreted text role "red".
warning. I have to domake clean html
and thenmake html
again. Other than this, everything works just fine. -
Turgut Sarıçam almost 5 yearsAmazing solution. As @umbe1987 said, compile errors occur when rebuilding the HTML. I managed to fix it using
rst_prolog
instead ofrst_epilog
. The difference is thatrst_prolog
includes the file at the beginning, whilerst_epilog
includes it at the end (Seerst_prolog
in Sphinx docs). -
ankostis about 4 yearsActually RsT already supports color-roles by including the
<s5defs.txt>
"standard" definition file (see my answer, below). -
shaan almost 4 yearsAn outright easy to follow solution for something which should not have been such a big deal in the first place. Thank you. One problem I faced though - i.e. with the
.. default-role::
inrst-prolog
inconf.py
file, my page layout was going haywire. Initially I made major changes in the.css
file. But in the end I realized that.. default-role::
was the real culprit. Removing it made everything fall in place. Including the font color!! -
ankostis almost 4 yearsThank @shaan! Fixed.