Contributing to Dallinger Documentation
=======================================

Dallinger's documentation is written using reStructuredText markup, and transformed into
HTML markup using `Sphinx <https://www.sphinx-doc.org/en/master/>`__.

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

