triage icon indicating copy to clipboard operation
triage copied to clipboard

Implement Triage API reference to supplement current docs

Open adunmore opened this issue 4 years ago • 4 comments

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 avatar Jun 15 '20 20:06 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.

adunmore avatar Jun 19 '20 19:06 adunmore

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 avatar Jun 19 '20 20:06 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

thcrock avatar Jun 19 '20 20:06 thcrock

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.

adunmore avatar Jun 25 '20 14:06 adunmore