API documentation: automated docs builds

[StephenChan]

Branched from #190. Currently this isn't that important because we only have 4 API endpoints (with deploy being the only supported workflow). But if we add many more in the future, there's going to be a lot of potential for typos in manually-written docs. Endpoint URLs, parameter names/formats, etc. Making changes to the spec becomes a bit of a hassle as well.

Here are the ideas from #190:

---

django-rest-framework has some support and for documenting an API: http://www.django-rest-framework.org/topics/documenting-your-api/ The gist of it is that we would write triple-quoted docstrings for our API-view functions, such as the following, and they should end up in the API documentation:

class UserList(generics.ListCreateAPIView):
    """
    get:
    Return a list of all the existing users.

    post:
    Create a new user instance.
    """

And then on top of that, we would use one of several third-party apps to go on top of django-rest-framework and provide a nice documentation interface. For example, drf-yasg, DRF-OpenApi, Django REST Swagger. These are listed in the previous link as well.

Also might look into: sphinx-apidoc

A lot of endpoints are going to have similar parameter formats and response formats. To avoid writing the same documentation twice, consider using references and definitions as described here: https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md For example, a common Metadata definition would save us from having to describe latitude, longitude, aux1, aux2, water_quality, etc. a million times. In general, we could have one definition per database model.