autogenerate API documentation

[n2ygk]

Fixes #478

Description of the Change

Autogenerate API reference documentation from the Python docstrings, superseding docs/api.md which is out of date.

Checklist

• PR only contains one change (considered splitting up PR)
• documentation updated
• changelog entry added to CHANGELOG.md
• author name in AUTHORS

[n2ygk]

I'm not quite sure if I the .travis.yml update I did is actually useful....

Adding tox -e sphinx I think is useful as one can at least locally regenerate the docs to see if the docstrings are useful/readable.

[n2ygk]

@sliverc please take a look at this. I'm not sure how to test pushing these changes to readthedocs.org

[n2ygk]

I seem to have figured out how to test RTD. See https://testing-django-rest-framework-json-api.readthedocs.io/en/sphinx-apidoc/

[sliverc]

Nice work 👍 This is a good improvement to our documentation.

I am not a sphinx expert but I have seen in other projects that it should be completely auto generatable without the need of a bunch of apidoc rst files.

One of them is SpiffWorkflow. Maybe we can have a look there how it is done. Makes maintaining API documentation even easier as we do not have to think about adding any new modules to the sphinx doc.

[n2ygk]

I am not a sphinx expert but I have seen in other projects that it should be completely auto generatable without the need of a bunch of apidoc rst files.

Those apidoc files are "autogenerated" by sphinx-apidoc (via tox -e sphinx) but I would love to not even have to remember to do that step since the updated files then have to be committed/pushed. I'll try and take a look at SpiffWorkflow or other options, unless your or someone else wants to chime in with a commit here, which I would welcome.

Should use reST or MarkDown in docstrings? I prefer the later, but it seems reST is the dominant case and it's not a big deal to have to use .. code:: python instead of ```python

[sliverc]

@n2ygk Let's use reST as it is more powerful and in the long run I would prefer that we only use reST in the whole project (otherwise it is fairly confusing in what context what markup language needs to be used)

I unfortunately do not have a lot of experience with sphinx so if someone else with experience could look at this as well that would be great.

[n2ygk]

@sliverc this is based off my latest commits to #481 based on your review. Assuming you merge that with no further changes, this should also be ready for review and squash merge.

[sliverc]

Great work.

Two comments:

• Could you resolve the merge conflicts and rebase with master?
• The API reference of filters promotes sort and queryvalidation package, although the API we want to promote would be rather filters import directly. DRF also adds their filter backends into one module and does not split it up into several files. I guess we could do the same? I would prefer it.

[n2ygk]

• The API reference of filters promotes sort and queryvalidation package, although the API we want to promote would be rather filters import directly. DRF also adds their filter backends into one module and does not split it up into several files. I guess we could do the same? I would prefer it.

I will stick them back together. Even though filters/__init__.py makes it look that way by importing from the sort.py and queryvalidation.py, that isn't apparent from the sphinx autoapi.

[sliverc]

Great. Thanks.