reStructuredText and Sphinx Reference

Example based gentle reference of the reStructuredText and Sphinx syntax, directives, roles and common issues. It demonstrates almost all the markup making it also good for testing Sphinx themes. Free and open-source.

inline literal

Inline literal element is typically used for short code examples displayed in monospace font.

Inline literal syntax

Inline literal syntax is simple: wrap the text between two ``.

1To search on your disk, use ``find`` command.

To search on your disk, use find command.

Alternative syntax

Alternative to enclosing into `` is to use a full role syntax: :literal:`text`.

1To search on your disk, use :literal:`find` command.

To search on your disk, use find command.

No inline element nesting

The annoying reStructuredText limitation is you can’t nest inline element into another, e.g. inline literal into strong emphasis, etc. Unfortunately, there is no workaround.

Some examples of inline markup nesting that don’t work:

1*You can't have **bold** inside italic.*
3**A |substitution| inside bold.**
5*A :subscript:`subscripts` inside italic.*
7``Or, *italic* within literals.``
9:ref:`link with ``literal`` inside`

You can’t have **bold* inside italic.*

A |substitution| inside bold.

A :subscript:`subscripts` inside italic.

Or, *italic* within literals.

link with ``literal` inside`

Requires whitespace or punctuation around

The inline literal requires whitespace or punctuation around (as all inline-level elements). Without the delimiter, reStructuredText will not recognize markup properly from a surrounding text.

The following examples miss a delimiter at the end, the beginning, and at the both. They will cause the WARNING: Inline literal start-string without end-string.

1Any ``array``s will suffice.
3Any``array`` will suffice.
5Any``array``s will suffice.

Fortunately, two inline elements without no whitespace/punctuation in-between are possible with escaping mechanism using backslash-escaped whitespace (backslash is \). Backslash-escaped whitespace will be removed from the output document.

Previous example fixed:

1Any ``array``\ s will suffice.
3Any\ ``array`` will suffice.
5Any\ ``array``\ s will suffice.

Any arrays will suffice.

Anyarray will suffice.

Anyarrays will suffice.

Previous: inline image | Next: note