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.4. Links (RST:004)

Links MUST be checked for availability. This is ensured by running sphinx in linkcheck mode.

Links rules

• All links MUST be reachable.

• Separated link and target definition SHOULD be used. If link and target definition are separated the target MUST be defined at the end of the file after two blank lines.

Examples:

Listing 2.40 description of external links in rst-files

 |foxbms| is developed by the `Battery Systems Group`_ at `Fraunhofer IISB`_.

 more documentation
 even more documentation

 .. Battery Systems Group: https://www.iisb.fraunhofer.de/en/research_areas/intelligent_energy_systems/stationary_battery_systems.html
 .. Fraunhofer IISB: https://www.iisb.fraunhofer.de

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

 .. 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.

• reStructuredText file rst.rst