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:
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):
Line numbering¶
code-block example can be automatically line numbered by :linenos: option.
1for (let i = 0; i < 3; i++) { // shows 0, then 1, then 2
2 alert(i);
3}
.. 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.
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.
1for (let i = 0; i < 3; i++) { // shows 0, then 1, then 2
2 alert(i);
3}
.. 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