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 a
vertical bar (“|”).
Line breaks and initial indents
are 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}