2.4. reStructuredText Coding Guidelines

These coding guidelines MUST be applied to all reStructuredText source files.

The following rules generally apply and follow the naming schema RST:<ongoing-number>.

2.4.1. Filenames (RST:001)

Additional to the general file naming rules the following MUST be applied.

File name rules

  • reStructuredText source files MUST use .rst as file extension.

For example the valid file names for a reStructuredText sources are

  • macros.txt

  • software-installation.rst

2.4.2. Linelength (RST:002)

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 (RST:003)

Include macros to have consistent style for repetitive words.

Include rules

  • Macros SHOULD be used where ever it is possible within the build toolchain.

  • macros.txt MUST 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 macros.txt.

2.4.5. Headings (RST:005)

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

heading

  • all reStructuredText files MUST have a heading

  • the heading MUST be two lines after the file label

  • the heading MUST be underlined with =

Listing 2.41 heading of guidelines_rst.rst
1
2
3
4
5
6
 .. include:: ./../../macros.txt

 .. _RESTRUCTUREDTEXT_CODING_GUIDELINES:

 reStructuredText Coding Guidelines
 ==================================

2.4.6. Orphan (RST:006)

orphan

  • reStructuredText files which are not included in other .rst files MUST start with :orphan:

2.4.7. File Templates

This file template below show how these rules are correctly applied. It SHOULD be used as basis for new files.