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