Documenting Indivo¶
Indivo’s documentation (as of version 1.0) is written using the Sphinx documentation framework, and is hosted by Read the Docs. Additionally, we’ve added some mechanisms to autogenerate documentation for our Indivo API and python client.
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 source, located in indivo_server/doc/sphinx/source. For a good primer on writing documentation in reStructured Text, see The Sphinx team’s overview.
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 to our Indivo Server repository, and we’ll review your changes and add them to the project documentation.