Contributing to Dallinger Documentation

Dallinger’s documentation is written using reStructuredText markup, and transformed into HTML markup using Sphinx.

The formal narrative documentation source lives in .rst files inside dallinger/docs/source/. These are the files that should be edited (or added to) when updating documentation. The build directory holds the output generated by Sphinx, and should not be edited directly.

Sphinx also builds automatic documentation for Python and Javascript code based on inline docstring and jsdoc in source files.

Building Documentation Locally

Sphinx and reStructuredText can be tricky to get right without some trial and error, so you will probably want to build documentation locally after making additions or changes, so you can preview the generated, styled HTML. There are two ways to do this.

Tox (aka “The Big Hammer”)

Running tox to build documentation will download the current release of Dallinger, install all dependencies, and build documentation based on this. If you’re working on a proposed change, this is probably not what you want to do:

tox -e docs

Building from Your Current Local Source

To build your working copy of the documentation using your already installed development verison of Dallinger, you’ll first need to run yarn to install Javascript dependencies from npm. From the root of the main Dallinger directory:

yarn

You can then generate the documentation:

make -C docs html

If you’ve made syntactical errors in your reStructuredText, you’ll get warnings and/or errors:

/Users/you/Dallinger/docs/source/running_the_tests.rst:84: WARNING: Title underline too short.

When complete, you can open the root index.html page in a web browser:

open docs/build/html/index.html