Code blocks
See, how code blocks look like in the Awesome Theme.
Sphinx code-block directive
To document code blocks with syntax highlighting,
use Sphinx’s
directive.
If you don’t provide an explicit language to the directive, a fallback is used:code-block
You used the
directive to set a default on a per-document basis. Any code block after this directive is highlighted with the language you specified.highlight
You set the global fallback language for highlighting in the Sphinx configuration file with the
highlight_language
option.
See also
You can provide the language for syntax highlighting to the
directive:code-block
.. code-block:: python
print("Hello World")
This renders as:
print("Hello World")
All code blocks have a Copy button. Clicking the button copies the code to the clipboard.
Add captions to code blocks
You can provide captions to code blocks with the :caption: CAPTION_TEXT
option:
Show line numbers in code blocks
You can show line numbers in code blocks with the :linenos:
option:
1for i in range(3):
2 print(f"{i} line of code")
Highlight lines in code blocks
To emphasize specific lines in code blocks, use the
:emphasize-lines: LINE_NUMBERS
option:
echo "Don't emphasize this"
echo "Emphasize this"
echo "Don't emphasize this either"
Highlight changes in code blocks
Often, you want to highlight what code need to be changed.
With the Awesome Theme, you can use the following options for the
directive:code-block
To highlight lines, that need to be added, use
:emphasize-added: LINE_NUMBERS
.To highlight lines that need to be removed, use
:emphasize-removed: LINE_NUMBERS
.
print("red")
print("green")
print("regular highlighting is applied")
The :emphasize-added:
and :emphasize-removed:
options preserve the highlighting
of the code. If you copy the code, the +
and -
characters aren’t copied.
If you don’t want to use these options, you can use Pygments built-in diff
language:
+ print("red")
- print("green")
print("no highlighting is applied here")
Here, the syntax isn’t highlighted.
If you copy the code to the clipboard,
the +
and -
characters 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:
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.")
You can’t include reStructuredText markup in code blocks, such as bold text or hyperlinks.
Docutils code directive
The
directive only works with Sphinx.
If you want to re-use your reStructuredText documentation outside Sphinx,
you can also use the code-block
code
directive:
echo "This is rendered with the docutils' code directive"
You can’t use captions, highlighted lines, or any of the other options for Sphinx code blocks.
Parsed literal blocks
If you want to write blocks of literal text containing any markup, such as bold text or
hyperlinks, use a
directive.parsed-literal
This can contain markup, but not syntax highlighting.
You can’t use syntax highlighting with
blocks.parsed-literal