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.
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:
To show code examples as block element you have more choices.
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.
Literal block ends with the return to the original 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.
Much richer block code examples you can craft with code-block directive. It allows syntax highlighting, line numbering, emphasis particular lines and using captions.
Language to highlight is set as directive argument, i.e.
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
json, … as a code-block argument.
If you don’t want any highlighting, use
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):
code-block example can be automatically line numbered by
Particular line number may be emphasized with
:emphasize-lines:line_number option. Multiple lines are comma separated (e.g.
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.
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.
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:
Creating code examples as inline elements is simple as wrapping text with two backtick:
``code example``. It doesn’t support syntax highlighting.
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.