ReStructured Text (RST) is a markdown language with additional directives for table of contents, tables and footnotes, among other things. It can also be configured to pull docstrings directly from the code base. Sphinx is a python-based document generator which converts RST into HTML docs for browsing and searching. Gulp is used as a makefile and to convert LESS stylesheets into CSS.

Web-based Updates

Github can be used to do most page updates. To begin, click on the ‘edit on github’ link at the top right of the page you’d like to edit. Log in to your github account; or create one and verify your email address.

The primary repository can not be edited directly; github will prompt you to create your own copy, called a fork. Edit the file using and preview the changes. When you are finished, write a quick summary of the change and click “Propose file change”. This will create a pull request and notify the development team of the suggested update. Once accepted, the documentation will automatically be updated on develop branch.



If you’re updating docs locally, you’ll need to install a few python modules. This is required because Sphinx reads docstrings from the code base and adds them to the documentation:

pip install tests/modules.txt
pip install docs/requirements.txt

Next you’ll need to install a few node-based tools which are used to process the visual theme: Node Package Manager and Yarn.

brew install npm yarn (for mac osx) or apt-get install npm yarn (for linux)

Assuming you have the redeem git repo already cloned, install the remainder of the node packages:

$ cd redeem/docs
$ yarn

To build the docs:

``$ gulp docs``

Or if you’d like it to build every time a change is made to code or docs, use gulp watch.

The output is placed in the /docs/_build/html directory and, since it’s static, can be opened directly from a browser.

Mediawiki to RST

Pandoc is a tool that converts between multiple different markup and markdown formats. When converting from mediawiki to restructured text, it converts about 90% of the formatting without need for manual refactoring.

To install: brew install pandoc

To convert from mediawiki:

  1. go to the mediawiki page and click Edit
  2. copy and paste the content into a text file. eg.
  3. run pandoc: pandoc -r mediawiki -w rst > mywikipage.rst
  4. edit as needed

Release Build (Versions)

The build process which produces the current and past versions of the documentation requires that all files are committed, pushed and have a tag with the format of X.X or X.X.X. There is a gulp command that handles all of the configuration:

$ gulp build-versions

Example section title

Example section title

Example sub-section title

Example sub-section title.

Commonly Used Syntax


emphasis is rendered as italics

strong emphasis is rendered as bold


literal is used for highlighting code or commands inline.

def blockOfCode(a, b):
    return a + b


  • a
  • list
  • of
  • unordered
  • things
  1. a
  2. list
  3. of
  4. ordered
  5. things

Footnotes : reference

Here is a paragraph that has two footnotes [1]; the actual footnote is displayed at the end of this document [2]


Simple Table Of Rows and Columns
Item 1 a b c d e
Item 2 f g h i j
Item 3 k l m n o
Item 4 p q r s t



a piece of information to be highlighted


information that is thought of as a best practice. read more about it here.


this should be used to highlight a backwards incompatible change


do not do this as something maybe damaged or lost

New in version X.Y.Z.


An image is shown as a thumbnail; full size is viewable by clicking on it:


Figures have other options, including using a caption:


A caption describing this figure.

Footnotes: notes

[1]Text of the first footnote.
[2]Text of the second footnote.

Code Documentation

Docstrings should use the NumPY format. Source code for these examples can be found at NumPY Docstring Example

example.function_with_types_in_docstring(param1, param2)

Example function with types documented in the docstring.

PEP 484 type annotations are supported. If attribute, parameter, and return types are annotated according to PEP 484 they do not need to be included in the docstring:

  • param1 (int) – The first parameter.
  • param2 (str) – The second parameter.

True if successful, False otherwise.

Return type:


example.module_level_function(param1, param2=None, *args, **kwargs)

This is an example of a module level function.

Function parameters should be documented in the Parameters section. The name of each parameter is required. The type and description of each parameter is optional, but should be included if not obvious.

If *args or **kwargs are accepted, they should be listed as *args and **kwargs.

The format for a parameter is:

name : type

    The description may span multiple lines. Following lines
    should be indented to match the first line of the description.
    The ": type" is optional.

    Multiple paragraphs are supported in parameter
  • param1 (int) – The first parameter.
  • param2 (str, optional) – The second parameter.
  • *args – Variable length argument list.
  • **kwargs – Arbitrary keyword arguments.

True if successful, False otherwise.

The return type is not optional. The Returns section may span multiple lines and paragraphs. Following lines should be indented to match the first line of the description.

The Returns section supports any reStructuredText formatting, including literal blocks:

    'param1': param1,
    'param2': param2

Return type:


  • AttributeError – The Raises section is a list of all exceptions that are relevant to the interface.
  • ValueError – If param2 is equal to param1.

Generators have a Yields section instead of a Returns section.

Parameters:n (int) – The upper limit of the range to generate, from 0 to n - 1.
Yields:int – The next number in the range of 0 to n - 1.


Examples should be written in doctest format, and should illustrate how to use the function.

>>> print([i for i in example_generator(4)])
[0, 1, 2, 3]
exception example.ExampleError(msg, code)

Exceptions are documented in the same way as classes.

The __init__ method may be documented in either the class level docstring, or as a docstring on the __init__ method itself.

Either form is acceptable, but the two should not be mixed. Choose one convention to document the __init__ method and be consistent with it.


Do not include the self parameter in the Parameters section.

  • msg (str) – Human readable string describing the exception.
  • code (int, optional) – Numeric error code.

str – Human readable string describing the exception.


int – Numeric error code.

class example.ExampleClass(param1, param2, param3)

The summary line for a class docstring should fit on one line.

It may include what the purpose of this class is and how it should be used.

More detail on what gets initialized

  • param1 – The first parameter.
  • param2 – The second parameter.
attr1 = None

description of the various class attributes

attr2 = None

Description of attr1

attr3 = None

Doc comment inline with attribute

attr4 = None

list of str – Doc comment before attribute, with type specified

attr5 = None

str – Docstring after attribute, with type specified.

example_method(param1, param2)

Class methods are similar to regular functions.


Do not include the self parameter in the Parameters section.

  • param1 – The first parameter.
  • param2 – The second parameter.

True if successful, False otherwise.

Return type:



str – Properties should be documented in their getter method.


list of str – Properties with both a getter and setter should only be documented in their getter method.

If the setter method contains notable behavior, it should be mentioned here.