11. Literal Text

Literal text in a reStructuredText context is (loosely) text which is text in which no markup processing is performed.

11.1. In-Line Literal Text

11.1.1. Decorated In-Line Literal Text

This is an in-line (here -->) ``literal`` string.

Result: This is an in-line (here –>) literal string.

As you can see, the word “literal” above looks different than the surrounding text. This is done by Sphinx (using Docutils internally) marking that text in HTML like this:

Result:  This is an in-line (here –&gt;)
<code class="docutils literal notranslate"><span class="pre">literal</span></code>
string.

which gives a wide latitude for the (customizable) theme to perform formatting on such text using CSS. Indeed, what you see above is done with CSS.

11.1.2. Interpreted Role Literal Text

There is a built-in interpreted role that can also be used for literal text:

This is :literal:`some  text  here  that  is  meant  to  be  literal  with  added  spaces`.

Result:

This is some text here that is meant to be literal with added spaces.

11.1.3. Default Interpreted Role

The default Interpreted-Text Role can be set so that un-decorated interpreted text (text merely surrounded with single back-quotes). You can do this by adding the following line to your conf.py file:

default_role = 'literal'

Then text like this:

This is a `literal` string.

will look like this in the output HTML:

This is a literal string.

Note

This is generally not advised so that writers do not get into the habit of using single back-quotes to mean literal text.

11.2. Literal Blocks

Literal blocks are defined as areas of text in which no markup processing is done.

The following are different ways of placing literal, pre-formatted blocks into your text.

11.2.1. Indented Literal Blocks

::

    Anything here and on subsequent lines.
    Note that the :: only has to be at the end
    of the line, so it could have text before it.

Some text here::

    Anything here and on subsequent lines.
    Note that the :: only has to be at the end
    of the line, so it could have text before it.

        Lines can be intended relative to surrounding text in block.

Result:

Anything here and on subsequent lines.
Note that the :: only has to be at the end
of the line, so it could have text before it.

Some text here:

Anything here and on subsequent lines.
Note that the :: only has to be at the end
of the line, so it could have text before it.

    Lines can be intended relative to surrounding text in block.

The Pygments library manages the language highlighting in these paragraphs. If you are getting highlighting you didn’t count on, check your conf.py file for the highlight_language setting. highlight_language = 'text' can be set for “no highlighting”.

Any indentation level is acceptable. The literal block ends with the end of the indentation.

11.2.2. Quoted Literal Blocks

Quoted literal blocks are created exactly like Literal Blocks except instead of indenting the quoted block, you begin each line of it with a printable non-alphanumeric ASCII character. Any of these characters can be used to lead the quoted block, so long as each quoted line begins with the same one:

! “ # $ % & ‘ ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` { | } ~

John Doe wrote::

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

You just did!  ;-)

Result:

John Doe wrote:

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

You just did! ;-)

11.2.3. Text Code Blocks

Another unusual way of generating literal text is to enclose it in a code-block directive like this:

.. code-block:: text

    Literal text here

Result:

Literal text here

11.2.4. Doctest Blocks

Doctest blocks are interactive Python sessions cut-and-pasted into docstrings. They are meant to illustrate usage by example, and provide an elegant and powerful testing environment via the doctest module in the Python standard library.

Doctest blocks are text blocks which begin with the Python interactive interpreter main prompt (>>> followed by a space) and end with a blank line. Doctest blocks are treated as a special case of literal blocks, without requiring the literal block syntax. If both are present, the literal block syntax takes priority over Doctest block syntax:

This is an ordinary paragraph.

>>> print 'this is a Doctest block'
this is a Doctest block

Result:

This is an ordinary paragraph.

>>> print 'this is a Doctest block'
this is a Doctest block

The following is a literal block:

>>> This is not recognized as a doctest block by
reStructuredText.  It *will* be recognized by the doctest
module, though!

Indentation is not required for doctest blocks.

11.3. Block Quotes

A text block that is indented relative to the preceding text, without preceding markup indicating it to be a literal block or other content, is a block quote. Do not mistake these for literal blocks—they are not. Reason: all markup processing (for body elements and inline markup) continues within the block quote.

This is an ordinary paragraph, introducing a block quote.

    "It is my business to *know things*.  That is my trade."

    ---Sherlock Holmes

Result:

This is an ordinary paragraph, introducing a block quote.

“It is my business to know things. That is my trade.”

—Sherlock Holmes

The theme may or may not use special formatting for block quotes.