=====================
Writing Documentation
=====================
Documentation falls into two categories: documentation for **users** and
documentation for **developers**. Developer documentation can be further broken
down into **in-line** and **standalone** documentation. Here we focus on
standalone documentation for developers. For information on in-line
documentation, visit here <www.ihavenotdonethis.wat>.

Note that while it is not necessary for developers to contribute standalone
documentation, we will **NOT** accept pull requests without sufficient in-line
documentation.

General guidelines
==================
When writing any kind of documenation, in-line or standalone, please try to
adhere to the following conventions:

* Please use proper grammar and spelling conventions.
* When writing & commenting Python code, try to adhere to PEP-8_ standards.
* Try to write as simply as possible, assume that non-native English speakers
  may be reading.

Sphinx
======
To generate the standalone documentation, we use a library called `Sphinx`_.
You can build the documentation locally or read it online at `ReadTheDocs`_.

Sphinx conventions
------------------
When working on standalone documentation, please use the following conventions:

* In section titles, capitalize only initial words and proper nouns.
* Whenever possible, wrap lines at 80 characters.
* In the interest of readability, seperate links and their target definitions. 
* **We Have, We Need** - Always capitalized in documentation, can be lowercase 
  in code. Can be abbreviated **WHWN**.

Directory structure
-------------------
All documentation can be found in the ``docs/`` folder of the root application.
Documentation intended for developers is contained in the ``docs/developer/``
folder. Each HTML page is built from an .rst file in the ``docs`` folder. 

Building the docs
-----------------
To build the HTML documentation, run ``make html`` from the ``docs/`` directory.
This will generate HTML in ``docs/_build``.

reStructuredText
----------------
Sphinx uses reStructuredText files to build HTML documentation. Every standalone
HTML page is built from an ``.rst`` file. Each ``.rst`` file contains plain-text
that is parsed and used to generate HTML.

Additional resources
--------------------
Use these resources to assist in documentation:

For a quick reference, see :ref:`rst-primer`.

`A Sphinx primer`_

.. _Sphinx: http://sphinx.readthedocs.org/en/latest/
.. _A Sphinx primer: http://www.sphinx-docs.org/rest.html
.. _ReadTheDocs: http://www.readthedocs.org/
.. _PEP-8: http://www.python.org/dev/peps/pep-0008/