Documenting Indivo
==================

Indivo's documentation (as of version 1.0) is written using the 
`Sphinx documentation framework <http://sphinx.pocoo.org/>`_, and is hosted by 
`Read the Docs <http://readthedocs.org/>`_. Additionally, we've added some 
mechanisms to autogenerate documentation for our :doc:`api` and 
:doc:`python client <py-client-reference>`.

Modifying the Docs
------------------

If you've changed the behavior of the Indivo code base (by adding or modifying 
API calls) or want to amend some of the language in our documentation, you'll
want to submit changes to the Indivo documentation. Here we describe the 
mechanisms by which you can alter the documentation.

Autogenerated Docs
^^^^^^^^^^^^^^^^^^

After adding, removing, or changing Indivo API calls, you should update our
autogenerated documentation to match. You can do that by:

* In ``indivo_server/``, run ``python manage.py generate_docs parse``. This
  will pull in the latest Indivo code to create an up-to-date skeleton 
  listing of all API calls supported by Indivo. This skeleton is written to
  ``indivo_server/doc/sphinx/autogen/api-skeleton.py``. If you've made 
  changes to the codebase, you should see output from this command listing 
  the API calls that have changed.

* Open up the skeleton file 
  (``indivo_server/doc/sphinx/autogen/api-skeleton.py``) with the editor of 
  your choice. You'll see a large python dictionary listing every call that
  Indivo supports. Simply find the call you've modified (by searching for 
  the path of the call, i.e. ``"/accounts/{ACCOUNT_EMAIL}"``).

* Update the fields that we couldn't autogenerate, including:

  * *url_params*: The parameters passed in via the URL. These will be
    autopopulated with a default description for common parameters, but you
    should modify them to be appropriately descriptive, i.e.::

      "url_params": { 
          'ACCOUNT_EMAIL': 'The email identifier of the Indivo Account used by the call.'
      },


  * *query_opts*: Available options to pass in via the querystring of the URL.
    This should be a dictionary, where keys correspond to valid parameters,
    and values are descriptions of the paramters, i.e.::

      "query_opts": { 
          'order_by': 'The field by which to order results. Available options are "date." '
      },

  * *data_fields*: Available options to pass in via the POST data of the request. 
    This should be a dictionary, where keys correspond to valid parameters,
    and values are descriptions of the paramters, i.e.::

      "data_fields": { 
          'record_id': 'The Indivo record identifier to associate the data with.'
      },

    If there are no parameters in the POST data, but simply raw data, use the key ``''``.
    For example, the documentation for the call to post a new document looks like::

      "data_fields": {
          '': 'The raw content of the document to create.'
      },

  * *return_desc*: A description of the data returned by the call.

  * *return_ex*: An example of a return value for the call.

  * *deprecated*, *added*, and *changed*. Indicators of when the call was added, modified,
    or deprecated, if applicable. Entries should be the form of python tuples containing the 
    version where the change occurred, and a message describing the change (or the empty 
    string if no message is appropriate). For example, ``"added": ('2.0.0', '')`` describes
    a call added in version 2.0, and ``"deprecated": ('2.0.0', 'Use call foobar instead')``
    describes a call that has been deprecated in version 2.0, and should be replaced by the 
    foobar call.

**Note**: Some of the fields that are autogenerated (such as "description" and "access_doc") are 
pulled directly from the python docstrings of code functions. Make sure that all functions 
you write in the code have a concise, one-line description as the first line of their docstring.

Other Changes to the Docs
^^^^^^^^^^^^^^^^^^^^^^^^^

If you'd like to make other changes to the docs (say, add a new page describing some functionality
or change the language to be more accurate in an existing page), you should simply modify the 
`reStructured Text <http://docutils.sourceforge.net/rst.html>`_ source, located in 
``indivo_server/doc/sphinx/source``. For a good primer on writing documentation in reStructured Text, 
see `The Sphinx team's overview <http://sphinx.pocoo.org/rest.html>`_.


Building the Docs Locally
-------------------------

Once you've made the desired changes to the documentation, you can (and should) test that the docs
compile and look appropriate locally before submitting your changes to the project. To do so,

* Run ``python manage.py generate_docs build`` from the ``indivo_server/`` directory, which will
  build the autogenerated docs into an API reference and then build the Sphinx project itself. 
  Currently, you should see a few warning messages when the docs build: that's fine. Make sure you
  haven't introduced any errors.

* Open (in a browser) the compiled files, which are located in ``indivo_server/doc/sphinx/build/html``.
  You'll see a local copy of the documentation, which you can check to see if your modifications worked
  as expected. Note that the styles of the local documentation aren't as pretty as they are on our public
  readthedocs documentation: we just threw up something basic locally. You didn't do anything wrong,
  though--we promise.

* Continue to iterate, modifying the docs, then running ``generate_docs build``, until the results are
  to your satisfaction.

Getting Your Changes into the Official Docs
-------------------------------------------

After you've made changes to the docs, and tested them locally, you should submit them to the Indivo team
so that we can pull them into the official copy. Please submit a 
`Github Pull Request <https://help.github.com/articles/using-pull-requests>`_ to our 
`Indivo Server repository <https://github.com/chb/indivo_server>`_, and we'll review your changes and add
them to the project documentation.