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.


Another 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.).

Basic usage

Ability of parsed-literal to use inline markup is great for e.g., terminal session examples. The following example shows emphasis, strong emphasis and external hyperlink.

1.. parsed-literal::
3   *# Prints date only*
4   **$ date -I**
5   2020-03-03
7   Search for date in `man pages <>`_.
# Prints date only
$ date -I

Search for date in man pages.

Escaping inline markup

If you want to prevent recognizing inline markup in parsed-literal-block, you must protect it with backslash before it.

For example, For example, to render find foo instead of find foo you must type find \*foo\*. Compare the difference:

1.. parsed-literal::
3   # Escaped emphasis
4   $ find \*foo\*
6   # Not escaped emphasis
7   $ find *foo*
# Escaped emphasis
$ find *foo*

# Not escaped emphasis
$ find foo

Previous: paragraph | Next: rubric