Markup Style Guide¶
This page covers the conventions for writing and use of the reStructuredText (RST) markup syntax.
rST Primer¶
rST (reStructuredText) is a highly flexible markup language we use to write the manual. Due to its flexibility, we have a list of recommendations and conventions that editors of the guide should follow.
Headings¶
The heading hierarchy should be as follows:
Document Chapter¶
Document Section¶
Document Subsection¶
Document Sub-subsection¶
Syntax
****************
Document Chapter
****************
Document Section
================
Document Subsection
-------------------
Document Sub-subsection
^^^^^^^^^^^^^^^^^^^^^^^
Notes:
Please avoid having over 4 levels of heading hierarchy in a single chapter.
Each
.rstfile should only have one chapter heading (*).
Conventions¶
Three space indentation.
Lines should be less than 120 characters long.
Other loose conventions:
Avoid Unicode characters.
Avoid heavily wrapped text (i.e. sentences can have their own lines).