2.4. reStructuredText Coding Guidelines¶
These coding guidelines MUST be applied to all
The following rules generally apply and follow the naming schema
2.4.1. Filenames (
Additional to the general file naming rules the following MUST be applied.
File name rules
reStructuredTextsource files MUST use
.rstas file extension.
For example the valid file names for a reStructuredText sources are
2.4.2. Linelength (
Each line of text in your code SHOULD be at most 120 characters long. A line MAY exceed 120 characters if it is
a comment line which is not feasible to split without harming readability, ease of cut and paste or auto-linking, e.g., if a line contains an example command or a literal URL longer than 120 characters or
a raw-string literal with content that exceeds 120 characters. Except for test code, such literals should appear near the top of a file.
2.4.3. Include (
Include macros to have consistent style for repetitive words.
Macros SHOULD be used where ever it is possible within the build toolchain.
macros.txtMUST be included where ever possible
File local macros MAY be used. However, if a term is used in more than one file, the macro MUST be transferred to
2.4.5. Headings (
We follow the convention of the Python Developer’s Guide for Documenting Python. Use the following rules to create headings:
# with overline, for parts
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
“, for paragraphs
reStructuredTextfiles MUST have a heading
the heading MUST be two lines after the file label
the heading MUST be underlined with =
1 .. include:: ./../../macros.txt 2 3 .. _RESTRUCTUREDTEXT_CODING_GUIDELINES: 4 5 reStructuredText Coding Guidelines 6 ==================================
2.4.6. Orphan (
reStructuredTextfiles which are not included in other
.rstfiles MUST start with :orphan: