Inline code
See how inline markup looks like in the Awesome Theme.
On this page
To mark up code in inline text, you can:
Surround the code with two backtick characters.
Use the
code
interpreted text role.
Syntax highlighting in inline code
By default, Sphinx doesn’t highlight inline code. With the following extra steps, you can enable it.
Create a docutils configuration file
docutils.conf
in the same directory as the Sphinx configuration fileconf.py
.Add to the docutils configuration file
docutils.conf
:This makes
docutils
use short class names for syntax highlighting, the same setting as Sphinx uses to highlight code blocks.Note
This is necessary so that you can re-use the Pygments style sheet
pygments.css
that Sphinx already uses for code blocks.For each language you want to highlight, create a custom interpreted text role using docutils’
role
directive.For example, to highlight inline Python code, add the following code to the beginning of the reStructuredText file, in which you want to use the highlighting:
rst.. role:: python(code) :language: python :class: highlight
This renders a
code
element with a class ofhighlight
, which uses the highlighting styles from Pygments—the same as for code blocks.Use the new role to highlight inline code. For example:
rst:python:`print("Hello World")`
This renders
print("Hello World")
.
More interpreted text roles
Docutils and Sphinx come with many interpreted text roles to mark up specific elements. While this can be useful to convey semantic intentions in the reStructuredText source files, it’s a good idea to use only a few different roles:
The difference between the many roles are lost in the rendered output. Most of these roles are rendered like code (or bold).
Using too many directives puts a burden on documentation writers, who may be more familiar with the Markdown format. They have to agree and remember when to use which role.
The awesome theme only provides styles for the following interpreted text roles.
Files and directories
You can designate files with the file
role.
:file:`Some file name`
This renders as Some filename
. You can highlight placeholder text in file and
directory names using the following syntax:
:file:`/home/{USERNAME}/`
This renders as /home/USERNAME/
. If you want to distinguish directories from
file names, you can append a Slash (/
) character to directory names.
Inline code with placeholder text
To highlight inline code with placeholder text, use the samp
interpreted text
role:
:samp:`Replace {PLACEHOLDER}`
This renders as Replace PLACEHOLDER
.
Keyboard input
You can highlight keyboard combinations using the kbd
interpreted text role:
:kbd:`Ctrl+F`
This renders as Ctrl+F.
User interface elements
Graphical user interface elements are often rendered in a bold font.
Use the guilabel
role to highlight user interface elements, such as buttons:
:guilabel:`Help`
This renders as Help.
Use the menuselection
role to document items in menus.
:menuselection:`Start --> Program`
This renders as
.