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
These are the files that should be edited (or added to) when updating documentation. The
directory holds the output generated by Sphinx, and should not be edited directly.
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
from npm. From the root of the main Dallinger directory:
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: