Code blocks

This page shows awesome features of code blocks.

On this page

Highlight code blocks with Sphinx’ code-block directive

In most cases, you should use Sphinx’s code-block directive to mark up code blocks. If you don’t provide an explicit language to the directive, a fallback is used:

  • You can set the default fallback language for highlighting on a per-document basis using the highlight directive. Any code block after this directive are highlighted using that language.

  • You can set the global fallback language for highlighting in the Sphinx configuration file with the highlight_language option.

See also

highlight directive, highlight_language

Explicit is better than implicit. Unless all code blocks in your documentation are highlighted with the same language, always provide the highlighting language to the code block directive.

For example:

rst
.. code-block:: python

   print("Hello World")

renders as:

python
print("Hello World")

All code blocks have a Copy button. Clicking the button copies the code in the code block to the clipboard.

Sphinx’s code-block directives have many options:

You can add a caption using the :caption: CAPTION_TEXT option:

javascript Example code
.log("Hello World")

To show line numbers in the code block, use the :linenos: option:

python
1for i in range(3):
2   print(f"{i} line of code")

To emphasize specific lines in code blocks, use the :emphasize-lines: LINE_NUMBERS option:

bash
echo "Don't emphasize this"
echo "Emphasize this"
echo "Don't emphasize this either"

Highlight code changes

Often, you want to highlight, which code needs to be changed. The awesome theme adds two additional options to the code-block directive.

Use the :emphasize-added: LINE_NUMBERS option to highlight lines that need to be added to the code. Likewise, use the :emphasize-removed: LINE_NUMBERS option to highlight lines that need to be removed.

python
print("red")
print("green")
print("regular highlighting is applied")

The :emphasize-added: and :emphasize-removed: option allow the rest of the code to be highlighted in another language. The + and - characters aren’t copied with the code.

If you don’t want to use these option, you can use Pygments built-in diff format:

diff
+ print("red")
- print("green")
  print("no highlighting is applied here")

Note, how there’s no additional syntax highlighting. 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:

python
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:

python A really long line
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 code-block directive only works with Sphinx. If you want to re-use your documentation outside Sphinx, for example, rst2html, you can also use the code directive to mark up code blocks.

shell
echo "This is rendered with the docutils' code directive"

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.