rst Standards

We use reStructuredText to create our documentation. reStructuredText is a lightweight markup language designed to be both

  • processable by documentation-processing software such as Sphinx

  • easily readable by human programmers who are reading and writing Python or HTML code.

reStructuredText is very permissive on what tags you can use to format your documentation.

Shagility is notorious at not remembering the coding standards we have all agreed on for this doucmentaion, and so his rst code often uses random tags. So this page is a place where he can come to and remember the way it should be done before he rights the lates peice of documentation.

Heading Hyperink

The internal hyper link is the first linein the rst file and it uses the format of _xxxxx-xxxxxx-xxxxxx-xxxxx:

Headings

  • =, with overline, for h1 / chapters

  • =, for h2 / sections

  • -, for h3 / subsections

  • +, for paragraphs

  • #, for subparagraphs

Formatting

  • one asterisk: text for emphasis (italics),

  • two asterisks: text for strong emphasis (boldface), and

  • backquotes: text for code samples.