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.

Table of Contents

Intro

Collections

Elements

Etc.

transition

(Also known as divider or horizontal rule, or horizontal line.)

Transitions separate body elements and section. They are commonly seen in novels, as a gap spanning one or more lines, with or without a ornament. For example, in HTML they correspond to the <hr>.

Transition syntax

The syntax for a transition marker is a horizontal line of 4 or more repeated punctuation characters - typically - character.

1Transition marker is 4 or more repeated ``-`` character.
2
3----
4
5But often you type more characters.
6
7--------------------------
8
9The result will be the same.

Transition marker is 4 or more repeated - character.

But often you type more characters.

The result will be the same.

Requires blank lines before and after

1Para.
2
3----------
4
5Para.

Para.

Para.

Cannot begin a section or a document

Transition cannot appear at the beginning of a section or a document.

Section title
=============

----------

Para.

##############
Document title
##############

----------

Para.

Both above examples causes WARNING: unknown document: body element.

Cannot be followed by another transition

Two transitions may not be immediately adjacent.

Para.

----------

----------

Para.

Above example causes WARNING: At least one body element must separate transitions; adjacent transitions are not allowed.

Cannot be used in sidebar, topic, etc.

Transition cannot appear inside some container elements like sidebar or topic.

.. sidebar:: Transition

   cannot be used within some

   ----------

   elements like sidebar

The above will cause error WARNING: Unexpected section title or transition.

Previous: topic | Next: warning

On this page