General guidelines¶
Lines length¶
Wrap source lines so that lines length does not exceed 79 characters. This requirement matches PEP8 standards (from Python) and helps with side-by-side diffs on reviews.
Note
An exception to this rule is the content of code-block elements and links within the references.
When formatting a table that presupposes long lines of text, give
preference to one of the following methods over the table
directive:
Format a table using the
list-table
directive.Format a table using the
csv-table
directive.Format information as definition lists to avoid tables where possible.
Space and tab characters¶
Do not use tab characters within the code, use space characters instead.
Do not place space characters at the end of lines. If used, the linters test will fail because of trailing whitespaces.
Indentation¶
Use indentation very carefully and keep it consistent since it is significant for content nesting. Any indentation that differs from the previous one in length, terminates the current level of content either introducing a new content sublevel, or shifting to an upper content level.
Use indentation to format the nested content within:
Definition lists
Admonitions (notes, warnings, and so on)
Code blocks
List and CSV tables
For more information on how to format elements from the list above, see the related section of this chapter.