Techwriter at work blog.

Living and writing documentation at Documatt, small team of programmers that do write documentation too.


Showing code examples

In almost any technical documentation you need to show bits of code, filenames and paths, commands and console examples. They are usually styled in monospace font with optional syntax highlighting.

Block or inline level?

Before continuing, wait a second and thing if you want to show inline or block level code example. Even if you don’t know syntax at this moment, you will understand the difference:

../_images/block-vs-inline.png

Block code examples

To show code examples as block element you have more choices.

Literal block

Simplest are literal blocks that has two colons :: syntax followed by indented block. Above and bellow indented block must be blank line. Simplest are literal blocks that can’t be syntax highlighted.

In almost any documentation you need to show examples like:

def add(one, two):
    return one + two
In almost any documentation you need to show examples like:

::

    def add(one, two):
        return one + two

Literal block ends with the return to the original indentation.

In almost any documentation you need to show examples like:

def add(one, two):
    return one + two

Literal block ends with the end of the indentation.

In almost any documentation you need to show examples like:

::

    def add(one, two):
        return one + two

Literal block ends with the end of the indentation.

Paragraph ending with ::

Ending paragraph with colon followed by code example is very common. reStructuredText has special literal block syntax for it. If it find two colons at the end of paragraph followed by intented block, colons will replaced with one.

In almost any documentation you need to show examples like:

def add(one, two):
    return one + two
In almost any documentation you need to show examples like::

    def add(one, two):
        return one + two

Common issues

Missing blank line above indented block

Code example in intended block after :: must have blank line above and bellow. If you forgot blank line above you actually create definition list thus no error will be raised.

::

This is the definition of term ::, not a code example.

::
    This is the definition of term ::, not a code example.

code-block directive

Much richer block code examples you can craft with code-block directive. It allows syntax highlighting, line numbering, emphasis particular lines and using captions.

Syntax highlighting

Language to highlight is set as directive argument, i.e. .. code-block::language.

for (let i = 0; i < 3; i++) {        // shows 0, then 1, then 2
    alert(i);
}
.. code-block:: javascript

   for (let i = 0; i < 3; i++) {        // shows 0, then 1, then 2
       alert(i);
   }

Syntax highlighting uses library Pygments. Pygments calls supported highlight languages as lexers and it has a lexer for almost any language you might imagine – just use python, java, javascript, c++, html, json, … as a code-block argument.

Tip

If you don’t want any highlighting, use none or text.

See Pygments’s available lexers page for exhaustive reference. Argument for code-block is one of “short names” (the look of webpage at the time of writing):

../_images/pygments-lexers-webpage.png

Line numbering

code-block example can be automatically line numbered by :linenos: option.

1
2
3
for (let i = 0; i < 3; i++) {        // shows 0, then 1, then 2
    alert(i);
}
.. code-block:: javascript
   :linenos:

   for (let i = 0; i < 3; i++) {        // shows 0, then 1, then 2
       alert(i);
   }

Emphasizing lines

Particular line number may be emphasized with :emphasize-lines:line_number option. Multiple lines are comma separated (e.g. :emphasize-lines:10,12).

for (let i = 0; i < 3; i++) {        // shows 0, then 1, then 2
    alert(i);
}
.. code-block:: javascript
   :emphasize-lines: 2

   for (let i = 0; i < 3; i++) {        // shows 0, then 1, then 2
       alert(i);
   }

Captions

If you write more formal documentation, maybe you look for examples with :caption:caption option.

Basic for loop in JavaScript
for (let i = 0; i < 3; i++) {        // shows 0, then 1, then 2
    alert(i);
}
.. code-block:: javascript
   :caption: Basic for loop in JavaScript

   for (let i = 0; i < 3; i++) {        // shows 0, then 1, then 2
       alert(i);
   }

You can combine all possibilities together, indeed.

Basic for loop
1
2
3
for (let i = 0; i < 3; i++) {        // shows 0, then 1, then 2
    alert(i);
}
.. code-block:: javascript
   :caption: Basic for loop
   :emphasize-lines: 2
   :linenos:

   for (let i = 0; i < 3; i++) {        // shows 0, then 1, then 2
       alert(i);
   }

Common issues

Always specify highlight language

If you don’t tell code-block a highlight language, it’s not “autodetect” or “none” (plain text) as you might expect. A difficult series of conditions will find some language for you. For example default Sphinx highlight mode is python3. It’s better to always specify language with every code-block.

.. code-block::

   Nobody knows what highlight language will be used.

parsed-literal directive

Last option for showing code examples is parsed-literal directive. It can’t highlight code as code-block, but allows you to use reStructuredText inline markup (emphasis, hyperlinks, etc.). Very useful e.g. for terminal session examples.

# Prints date only
$ date -I
2020-03-03

Search for date in man pages.
.. parsed-literal::

   *# Prints date only*
   **$ date -I**
   2020-03-03

   Search for date in `man pages <https://manpages.ubuntu.com>`_.

Above example shows emphasis, strong emphasis and external hyperlink. If you prevent recognizing inline markup, you must protect it with backslash before it. To really show find *foo* instead of find *foo* you must type find \*foo\*. Compare the difference:

# Escaped emphasis
$ find *foo*

# Not escaped emphasis
$ find foo
.. parsed-literal::

   # Escaped emphasis
   $ find \*foo\*

   # Not escaped emphasis
   $ find *foo*

Inline code examples

Creating code examples as inline elements is simple as wrapping text with two backtick: ``code example``. It doesn’t support syntax highlighting.

To search on your disk, use find. It has very large number of options. General syntax looks like find <where> [-type f|d] -name <expression>. To search in correct folder, use . as <where>.

To search on your disk, use ``find``. It has very large number of options. General
syntax looks like ``find <where> [-type f|d] -name <expression>``. To search in current
folder, use ``.`` as ``<where>``.

Anything within begin and end backtick is handled as-is. Text will be shown in documentation exactly as written. You can neither use emphasis or any other inline markup. The benefit is that you don’t have you double or escape backtick character.

Inline literals can’t use inline markup. Text is shown *unchanged*. Even backtick ` in inline literal itself is printed as-is. Literal with backtick only ` is also easy to write.

``Inline literals`` can't use inline markup. Text is shown ``*unchanged*``. Even
``backtick ` in inline literal`` itself is printed as-is. Literal with backtick only
````` is also easy to write.

Common issues

Don’t interchange ` and ``

There is a big difference between `code example` and ``code example``! Only the latter with double `` is inline code example! Text wrapped in single ` is so-called default role interpreted text. See more in part about role anatomy.


Footnotes

Comments

comments powered by Disqus