Implement Triage API reference to supplement current docs

[adunmore]

The Triage docs currently have limited information on the Triage API. And while Triage is fairly-well covered by class- and function-level docstrings, it is inconvenient to access this documentation inside the source code.

Limited access to information about the Triage API poses challenges for development, debugging, and other low-level use cases.

Implementing an automated API reference documentation system like Sphinx would allow us to leverage existing source code documentation, creating a basic API reference site without too much pain.

Additionally, since Sphinx supports documents in the markdown format of our current docs, we could eventually integrate those with the new API reference docs.

[adunmore]

I just stumbled upon ~pydoc-markdown~ mkdocstrings, a tool for creating generating Markdown docs from Python docstrings, with MkDocs integration.

This would allow us to keep the existing docs stack, and to start integrating the API reference docs into the existing docs right away.

e: Originally linked the wrong library.

[thcrock]

You may also consider https://github.com/NiklasRosenstein/pydoc-markdown which we used for another DSaPP project.

The output from mkdocstrings looks nicer though.

[thcrock]

There's also a super-old attempt at doing this in Triage still in the repository:

https://github.com/dssg/triage/blob/master/docs/md_autogen.py

was called by (currently commented out):

https://github.com/dssg/triage/blob/master/docs/update_docs.py

[adunmore]

An update:

I've moved forward with mkdocstrings. It's implemented as a MkDocs plugin, so it integrates with our existing docs quite well. It doesn't add new steps to the docs build process or require any new files.

I used it to build a new reference page for Audition, and that went off smoothly. We'll just have to make sure that any docstrings we want to use are in the google docstrings style.