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.
Here is the citation for CIT2002
Click to go back to the link examples above: .. code-block:: rest