Code blocks and inline code
This page shows styles for inline markup related to code, as well as for the additional features of code blocks.
On this page
Inline Code
You can mark up generic inline code using two backticks
like this: inline code
.
Syntax highlighted inline code
If you want to use syntax highlighting for inline code,
such as this: print(“Hello World”)
,
perform these steps:
Create docutils configuration file
docutils.conf
.Place this file in the same directory as the Sphinx configuration file
conf.py
.Make the syntax highlighter use short class names.
Add this section to the file
docutils.conf
:This creates “short” class names for syntax highlighting, the same as used by Sphinx’s code blocks.
Define custom interpreted text roles using docutils
role
directive.For each language you want to highlight, create a custom interpreted text role. For example, to highlight inline Python code, add this to the beginning of the reStructuredText file:
rst.. role:: python(code) :language: python :class: highlight
This adds the class
highlight
to the list of classes for the inline code, which automatically applies the same styles as for code blocks.Use the new role to markup and highlight inline code.
For example:
rst:python:`print("Hello World")`
renders into
print(“Hello World”)
.
More interpreted text roles for code-like elements
Docutils and Sphinx come with many interpreted text roles to mark up specific elements. This theme only provides styles for a few of these roles.
Files can be marked up with the file
interpreted text role.
:file:`Some filename`
This is rendered as Some filename
.
You can highlight inline code with placeholders
using the samp
interpreted text role.
:samp:`Replace {PLACEHOLDER}`
This is rendered as Replace PLACEHOLDER
.
The same placeholder syntax can also be used with the file
role.
Keyboard shortcuts can be entered using the kbd
interpreted text role.
:kbd:`Ctrl+F`
This is rendered as Ctrl+F.
Interpreted text roles for GUI documentation
Graphical user interface elements are often rendered in a bold font,
in contrast to the monospace font for code elements.
Use the guilabel
role to document buttons and other
user interface elements.
:guilabel:`Help`
This renders as Help.
Use the menuselection
role to document items in menus.
:menuselection:`Start --> Program`
This renders as
.Awesome code blocks
You can render code blocks using the code-block
directive.
If you don’t specify a language as an argument to the code block,
the default highlighting language is used.
For example:
print("Hello World")
uses the Python lexer of Pygments to apply syntax highlighting.
Use the highlight
directive to set the default highlighting language
on a per-document basis. See
highlight directive
for more information.
Use the highlight_language
configuration setting to set the default
highlighting language for the whole project. See
highlight_language
for more information.
All code blocks have a header section with a Copy button. Clicking the button copies the text inside the code block to the clipboard. The header also contains a label for the highlighting language as well as the caption.
For interactive shell sessions, Pygments provides the shell-session
lexer, with an alias of console
. The former is too long and the
latter to old-fashioned for my taste.
This theme replaces the label console
with the label shell
in the header section of code blocks. Unfortunately, shell
is
also an alias for shell scripts. As shell scripts are likely to
be specific to a certain type of shell, I recommend being more
specific, such as using sh
, bash
, or zsh
.
If no highlighting language is defined, Sphinx uses default
,
which is translated to python (or interactive python session),
so this theme replaces default
with python
in the header
section.
The following example shows a code block for JavaScript with a caption.
Use the linenos
option to show line numbers in the code block.
1for i in range(3):
2 print(f"{i} line of code")
To emphasize specific lines in code blocks,
use the :emphasize-lines:
option:
echo "Don't emphasize this"
echo "Emphasize this"
echo "Don't emphasize this either"
Likewise, you can emphasize code changes using the :emphasize-added:
and :emphasize-removed:
options.
print("red")
print("green")
print("regular highlighting is applied")
Note, how the lines are still highlighted using Python syntax.
Copy the code and note, how the +
and -
characters aren’t
copied.
The :emphasize-added:
and :emphasize-removed:
options
only work in this theme. If you later change the theme, leaving
these options generate a warning and skip rendering all code
blocks with these options. I recommend using sphinx-build -W
to turn warnings into errors.
A portable, built-in alternative is to use Pygments’ diff
lexer.
+ print("red")
- print("green")
print("no highlighting is applied here")
This works with all themes, but doesn’t highlight the other lines
in the code block. When selecting the code to copy to the clipboard,
the +
and -
characters at the beginning are copied as well.
The following example is for testing the previous options with line numbers:
1print("One line of code")
2print("Removed line of code")
3print("Added line of code")
4print("Emphasized line of code")
5print("Normal line of code")
There is currently one visual bug with emphasizing lines #171.
For example:
print("A shorter line of code.")
print("And a really long line of code that should overflow the container on most screen sizes which illustrates the issue.")
Code blocks can’t contain any markup, such as bold text or hyperlinks.
Parsed literal blocks
If you want to write blocks of literal text containing any markup,
such as bold text or hyperlinks, use a parsed-literal
directive.
This can contain markup, but not syntax highlighting.
You can’t use syntax highlighting with parsed-literal
blocks.
Samp directive
If you want to highlight placeholder variables, and you can accept
only minimal highlighting, you can use the samp
directive.
For example:
is rendered as:
$ echo "Enter PLACEHOLDER"
The Sphinx awesome theme provides a style for the directive that integrates well with the rest of the theme. The parsing is handled by a separate extension sphinxawesome-sampdirective. This extension is automatically installed and loaded, if the Sphinx awesome theme is installed as a Python package. See How to install the theme for more information.
You can install and activate the extension separately for using with other themes.