Writing Documentation

Documentation falls into two categories: documentation for users and documentation for developers. Developer documentation can be further broken down into in-line and standalone documentation. Here we focus on standalone documentation for developers. For information on in-line documentation, visit here <www.ihavenotdonethis.wat>.

Note that while it is not necessary for developers to contribute standalone documentation, we will NOT accept pull requests without sufficient in-line documentation.

General guidelines

When writing any kind of documenation, in-line or standalone, please try to adhere to the following conventions:

• Please use proper grammar and spelling conventions.
• When writing & commenting Python code, try to adhere to PEP-8 standards.
• Try to write as simply as possible, assume that non-native English speakers may be reading.

Sphinx

To generate the standalone documentation, we use a library called Sphinx. You can build the documentation locally or read it online at ReadTheDocs.

Sphinx conventions

When working on standalone documentation, please use the following conventions:

• In section titles, capitalize only initial words and proper nouns.
• Whenever possible, wrap lines at 80 characters.
• In the interest of readability, seperate links and their target definitions.
• We Have, We Need - Always capitalized in documentation, can be lowercase in code. Can be abbreviated WHWN.

Directory structure

All documentation can be found in the docs/ folder of the root application. Documentation intended for developers is contained in the docs/developer/ folder. Each HTML page is built from an .rst file in the docs folder.

Building the docs

To build the HTML documentation, run make html from the docs/ directory. This will generate HTML in docs/_build.

reStructuredText

Sphinx uses reStructuredText files to build HTML documentation. Every standalone HTML page is built from an .rst file. Each .rst file contains plain-text that is parsed and used to generate HTML.

Additional resources

Use these resources to assist in documentation:

For a quick reference, see A beginner’s guide to reStructuredText.

A Sphinx primer