Appendix A - Documentation Standards

The Hercules documents are written in reStructuredText.

This appendix details the reStructuredText standards to be adhered to when creating or editing documentation, in order to achieve a consistent presentation of documenation across many contributors, and over time.

reStructuredText (RST) is a lightweight plaintext markup language, which is simple and human-readable in its raw form. It allows for easy conversion to other formats, such as PDF, HTML or EPUB. Read more on reStructuredText here .

This document is not intended to be a guide on RST - a basic familiarity with RST should be gained prior to working on documentation.

Section Standards

One of the first and most basic standards any documenter will need to know is that of Sections, used to establish a heirarchy, and build a table of contents. There is no definitive standard in place, however we will adopt the following which is commonly used with Python documentation.

The number of punctuation characters should match the length of the section name.

Top level ‘part’

######
Part 1
######

Surround the name by over- and underlining using # symbols.

2nd level ‘chapter’

*********
Chapter 1
*********

Surround the name by over- and underlining using * symbols.

3rd level ‘section’

Section 1
=========

Underlining using = symbols.

4th level ‘subsection’

Subsection 1
------------

Underlining using - symbols.

5th level ‘subsection’

Subsection 1
^^^^^^^^^^^^

Underlining using ^ symbols.