# Documentation¶

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.

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.

## Dependencies¶

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:



## Example section title¶

Example section title

### Example sub-section title¶

Example sub-section title.

## Commonly Used Syntax¶

### Emphasis¶

emphasis is rendered as italics

strong emphasis is rendered as bold

### Code¶

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]

### Table¶

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

### Highlighting¶

Important

a piece of information to be highlighted

Note

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

Warning

this should be used to highlight a backwards incompatible change

Danger

do not do this as something maybe damaged or lost

New in version X.Y.Z.

### Images¶

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

Figures have other options, including using a caption:

### 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:

Parameters: param1 (int) – The first parameter. param2 (str) – The second parameter. True if successful, False otherwise. bool
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
description

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
descriptions.

Parameters: 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 }  bool AttributeError – The Raises section is a list of all exceptions that are relevant to the interface. ValueError – If param2 is equal to param1.
example.example_generator(n)

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. int – The next number in the range of 0 to n - 1.

Examples

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.

Note

Do not include the self parameter in the Parameters section.

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

str – Human readable string describing the exception.

code

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

Parameters: 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.

Note

Do not include the self parameter in the Parameters section.

Parameters: param1 – The first parameter. param2 – The second parameter. True if successful, False otherwise. bool
readonly_property

str – Properties should be documented in their getter method.

readwrite_property

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.