Introduction to reST and Sphinx#

reStructuredText, commonly referred to as reST, is an easy-to-read plaintext markup syntax and parser system.

It is excellent for inline program documentation (such as Python docstrings), quickly creating simple web pages and standalone documents using Sphinx.

Paragraphs#

Paragraphs are text separated by one or more blank lines.

1This is some text in a paragraph.
2This is some more text in the same paragraph.
3Here is more text that is written in the first paragraph.
4
5This is some text in a New paragraph.

See Paragraph styling above rendered by Sphinx below.

This is some text in a paragraph. This is some more text in the same paragraph. Here is more text that is written in the first paragraph.

This is some text in a New paragraph.

Note

The next code block took from the following example of using text in a paragraph from here.

1Paragraphs contain text and may contain inline markup:
2*emphasis*, **strong emphasis**, `interpreted text`, ``inline
3literals``, standalone hyperlinks (http://www.python.org),
4external hyperlinks (Python_), internal cross-references
5(example_), footnote references ([#1]_), citation references
6([CIT2002]_), substitution references (|example|),
7and _`inline internal targets`.
8
9Paragraphs are separated by blank lines and are left-aligned.

See Paragraph styling above rendered by Sphinx below.

Paragraphs contain text and may contain inline markup: emphasis, strong emphasis, interpreted text, inline literals, standalone hyperlinks (http://www.python.org), external hyperlinks (Python), internal cross-references (example), footnote references ([2]), citation references ([CIT2002]), and inline internal targets.

Paragraphs are separated by blank lines and are left-aligned.

Indentation#

All indentation is significant; the level of indentation must be consistent. For example, indentation is the sole markup indicator for block quotes.

Note

This example of using text in a paragraph was taken from here

 1This is a top-level paragraph.
 2
 3 This paragraph belongs to a first-level blockquote.
 4
 5  This paragraph belongs to a second-level blockquote.
 6
 7This is another top-level paragraph.
 8
 9  This paragraph belongs to a second-level block quote.
10
11This paragraph belongs to a first-level block quote.  The
12second-level block quote above is inside this first-level
13block quote.

See Indentation styling above rendered by Sphinx below.

This is a top-level paragraph.

This paragraph belongs to a first-level blockquote.

This paragraph belongs to a second-level blockquote.

This is another top-level paragraph.

This paragraph belongs to a second-level block quote.

This paragraph belongs to a first-level block quote. The second-level block quote above is inside this first-level block quote

Further Reading#

For further interesting reading on this topic, see reST How-to Index


Example of links used in test.

[CIT2002]

Here is the citation for CIT2002

Click to go back to the link examples above: .. code-block:: rest