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.
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.
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.
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.
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,
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.