1.5. Paragraphs¶
The paragraph is the most basic block in a reStructuredText document. Paragraphs are simply chunks of text separated by one or more blank lines. As in Python, indentation is significant in reStructuredText, so all lines of the same paragraph must be left-aligned to the same level of indentation. General rules can be looked up under Use of whitespace.
- the example
1 2 3 4 5 6 7 8 9 10 11 12 13
Paragraphs are separated by blank lines. Line breaks in the source code do not create line breaks in the output. This means that you *could*, in theory, include a lot of arbitrary line breaks in your source document files. These line breaks would not appear in the output. Some people like to do this because they have been trained to not exceed 80 column lines, and they like to write :file:`.txt` files this way. Please do not do this. There is **no reason** to put a limit on line length in source files for documentation, since this is prose and not code. Therefore, please do not put arbitrary line breaks in your files.
- which gives
Paragraphs are separated by blank lines. Line breaks in the source code do not create line breaks in the output.
This means that you could, in theory, include a lot of arbitrary line breaks in your source document files. These line breaks would not appear in the output. Some people like to do this because they have been trained to not exceed 80 column lines, and they like to write
.txt
files this way. Please do not do this.There is no reason to put a limit on line length in source files for documentation, since this is prose and not code. Therefore, please do not put arbitrary line breaks in your files.
1.5.1. Quotes (block quotation) Element¶
Block quoted paragraphs are quoted by just indenting them more than the surrounding paragraphs.
- the example
1 2 3 4 5 6 7 8 9
This line is not a block quote. Block quotes are indented, and otherwise unadorned. This is a block quote. --Adam Michael Wood - `Technical Content Writer`_ .. _`Technical Content Writer`: http://adammichaelwood.com/portfolio/
- which gives
This line is not a block quote. Block quotes are indented, and otherwise unadorned.
This is a block quote.
—Adam Michael Wood - Technical Content Writer
-
.. pull-quote::
¶ Pull-quoted paragraphs are similar to block quotes but are directives for small selection of text to “pull out and quote”, typically in a larger typeface.
- The example
1 2 3 4 5 6 7 8 9 10 11
This line is not a pull quote. Pull quotes are directive content. .. pull-quote:: This is a pull quote. --Adam Michael Wood - `Technical Content Writer`_ .. _`Technical Content Writer`: http://adammichaelwood.com/portfolio/
- Which gives
This line is not a pull quote. Pull quotes are directive content.
This is a pull quote.
—Adam Michael Wood - Technical Content Writer
1.5.2. Line Blocks¶
Line blocks are useful for addresses, verse, and
adornment-free lists. They are quoted by just a |
pipe sign in front
of each single line.
- the example
1 2 3 4
| Each new line begins with a | vertical bar ("``|``"). | Line breaks and initial indents | are preserved.
- which gives
- Each new line begins with avertical bar (“
|
”).Line breaks and initial indentsare preserved.
1.5.3. Doctest Blocks¶
Doctest blocks are interactive Python sessions cut-and-pasted into docstrings. They do not require the literal blocks syntax. The doctest block must end with a blank line and should not end with an unused prompt, see Doctest blocks in Sphinx for more informations.
- the example
1 2 3 4 5 6 7 8 9 10 11 12
>>> print('this is a Doctest block') this is a Doctest block >>> print('Python-specific usage examples; begun with ">>>"') Python-specific usage examples; begun with ">>>" >>> print('(cut and pasted from interactive Python sessions)') (cut and pasted from interactive Python sessions) >>> a = [51,27,13,56] >>> b = dict(enumerate(a)) >>> print(b) {0: 51, 1: 27, 2: 13, 3: 56}
- which gives
>>> print('this is a Doctest block') this is a Doctest block
>>> print('Python-specific usage examples; begun with ">>>"') Python-specific usage examples; begun with ">>>" >>> print('(cut and pasted from interactive Python sessions)') (cut and pasted from interactive Python sessions)
>>> a = [51,27,13,56] >>> b = dict(enumerate(a)) >>> print(b) {0: 51, 1: 27, 2: 13, 3: 56}