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.

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.

../_images/forkandedit.png

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:

``$ 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. mywikipage.mw
  3. run pandoc: pandoc -r mediawiki -w rst mywikipage.mw > 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

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

Lists

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

../_images/replicapelogo.png

Figures have other options, including using a caption:

../_images/replicapelogo.png

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:

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

True if successful, False otherwise.
Return type:

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

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:

bool
Raises:
  • 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.
Yields: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.
Returns:

True if successful, False otherwise.
Return type:

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.