1.13. Code Example

The syntax for displaying code is the :: mark, see Literal blocks. When it is used at the end of a sentence, Sphinx is smart and displays one : sign in the output, and knows there is a code example in the following indented block, the Indented literal (code) block. Quoted literal (code) block are unindented contiguous blocks of text where each line begins with the same non-alphanumeric printable 7-bit ASCII character.

.. highlight::

For more details, see highlight directive.

The example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
.. highlight:: none

This is a normal text paragraph. The next paragraph
is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

The next paragraph is a quoted sample -- John Doe wrote::

>> Great idea!
>
> Why didn't I think of that?

You just did!  ;-)
Which gives

This is a normal text paragraph. The next paragraph is a code sample:

It is not processed in any way, except
that the indentation is removed.

It can span multiple lines.

This is a normal text paragraph again.

The next paragraph is a quoted sample – John Doe wrote:

>> Great idea!
>
> Why didn't I think of that?

You just did! ;-)

The handling of the :: marker is smart:

  • If it occurs as a paragraph of its own, that paragraph is completely left out of the document.

  • If it is preceded by whitespace, the marker is removed.

  • If it is preceded by non-whitespace, the marker is replaced by a single colon.

That way, the first sentence in the above example’s first paragraph would be rendered as “… The next paragraph is a code sample:”.

Sphinx extends the default language setup for each literal (code) block with the .. highlight:: directive. That is very useful if a specific directive is not able to set the language by argument or option, even in this case here.

1.13.1. Explicit Code Blocks

Source code will be formatted by the directive .. code-block::. Sphinx, like Python, uses meaningful whitespace. Blocks of content are structured based on the indention level they are on.

.. code-block::

For more details, see code-block directive.

The example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
.. highlight:: bash
   :linenothreshold: 1

A cool bit of code::

   #!/bin/bash
   # Some cool Bash code
   echo ${BASH_VERSINFO[*]}

.. highlight:: none

.. code-block:: rst
   :caption: Documentation

   A bit of **rst** which should be *highlighted* properly.

.. code-block:: python
   :caption: Script
   :linenos:

   import sys
   sys.exit(1)
Which gives

A cool bit of code:

1
2
3
#!/bin/bash
# Some cool Bash code
echo ${BASH_VERSINFO[*]}
Listing 1.2 Documentation
A bit of **rst** which should be *highlighted* properly.
Listing 1.3 Script
1
2
import sys
sys.exit(1)

Valid values for the highlighting :language: (first argument) are:

  • none (no highlighting)

  • python (the default)

  • c and cpp (C/C++)

  • rst or rest (reStructuredText)

  • bash or ksh or sh (Unix Shell scripts)

  • shell-session (Unix Shell sessions)

  • ps1 or posh or powershell (Windows PowerShell code)

  • ps1con (Windows PowerShell sessions)

  • dosbatch or winbatch (MS-DOS/Windows Batch file)

  • doscon (MS-DOS sessions)

  • cfg or ini (Generic configuration file, mostly INI files)

  • sql (Generic SQL commands)

  • registry (Windows Registry files produced by regedit)

  • guess (let Pygments guess the lexer based on contents, only works with certain well-recognizable languages)

  • … and any other lexer alias that Pygments supports.

1.13.2. Explicit Code Includes

If the text resides in a separate file, use the .. literalinclude:: directive:

.. literalinclude::

For more details, see literalinclude directive.

The example
1
2
.. literalinclude:: /docutils.conf
   :language: cfg
Which gives
;
; Docutils Configuration
;
; The configuration file consists of sections, lead by a "[section]"
; header and followed by "name: value" entries, with continuations
; in the style of RFC 822; "name=value" is also accepted. Note that
; leading whitespace is removed from values. ... Lines beginning
; with "#" or ";" are ignored and may be used to provide comments.
;
; see: https://docutils.sourceforge.io/docs/user/config.html
;

; https://docutils.sourceforge.io/docs/user/config.html#parsers
; https://docutils.sourceforge.io/docs/user/config.html#restructuredtext-parser

[restructuredtext parser]
syntax_highlight = short

All included files could be located under /include. The beginning / means, root directory of the documentation source directory. Without it, the path is relative to the directory of the including file.