.. _docs:

Writing documentation
=====================
Documentation for |owm| 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. To get the
``sphinx-build`` command, install the documentation requirements with::

    pip install -r doc-requirements.txt

Then, you can run ``sphinx-build`` like this::

    sphinx-build -w sphinx-errors docs <build_destination>

You can also invoke the command with default arguments (i.e., with output to
:file:`build/sphinx` using :file:`setup.py`::

    python setup.py build_sphinx

The docs will be compiled to html which you can view by pointing your web
browser at :file:`<build_destination>/index.html`. The documentation will be
rendered using the same theme as is used on the readthedocs.org site.


API Documentation
-----------------
API documentation is generated by the Sphinx `autodoc`_ and `apidoc`_
extensions. The numpydoc format should be easy to pick up on, but a reference
is available `here <b2_>`_. Just add a docstring to your function/class/method
and your class should appear among the other documented classes. Note, however,
that "special" methods like `__call__` will not show up by default -- if they
need to be documented for a given class, add a declaration like this to the
class documentation::

    class SpecialMethodDocExample:
        '''
        Example class doc

        .. automethod:: __call__
        '''

        def __call__(self):
            '''
            Hey, I'm in the API documentation!
            '''

.. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
.. _apidoc: https://github.com/sphinx-contrib/apidoc
.. _b2: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

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.