.. _docs:

Adding documentation
=====================
Documentation for |pow| is housed in two locations: 

    #. In the top-level project directory as :file:`INSTALL.md` and :file:`README.md`. 
    #. As a `Sphinx <http://sphinx-doc.org/>`_ project under the ``docs`` directory 

By way of example, to add a page about useful facts concerning C. elegans to
the documentation, include an entry in the list under ``toctree`` in
:file:`docs/index.rst` like::

    worm-facts

and create the file :file:`worm-facts.rst` under the :file:`docs` directory and
add a line::

    .. _worm-facts:

to the top of your file, remembering to leave an empty line before adding all
of your wonderful worm facts.

You can get a preview of what your documentation will look like when it is
published by running ``sphinx-build`` on the docs directory::

    sphinx-build -w sphinx-errors docs build_destination

The docs will be compiled to html which you can view by pointing your web
browser at :file:`build_destination/index.html`. If you want to view the
documentation locally with the `ReadTheDocs theme <a_>`_ you'll need to
download and install it.


.. _a: https://github.com/snide/sphinx_rtd_theme

API Documentation
------------------
API documentation is generated by the Sphinx `autodoc <b0_>`_ extension. The
format should be easy to pick up on, but a reference is available `here
<b1_>`_.  Just add a docstring to your function/class/method and add an
``automodule`` line to :file:`PyOpenWorm/__init__.py` and your class should
appear among the other documented classes.

.. _b0: http://sphinx-doc.org/ext/autodoc.html
.. _b1: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

Substitutions
-------------
Project-wide substitutions can be (conservatively!) added to allow for easily
changing a value over all of the documentation. Currently defined substitutions
can be found in :file:`conf.py` in the ``rst_epilog`` setting. `More about
substitutions <c_>`_

.. _c: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions

Conventions
-----------
If you'd like to add a convention, list it here and start using it. It can be
reviewed as part of a pull request.

1. Narrative text should be wrapped at 80 characters.
2. Long links should be extracted from narrative text. Use your judgement on
   what 'long' is, but if it causes the line width to stray beyond 80
   characters that's a good indication.