Let's talk documentation

[zackkrida]

We'll ultimately want to improve our code documentation in all repositories, and generate the handbook pages so that it's kept in sync with the repositories. This way we will have duplication, but also consistency and redundancy. We need to figure out a way to do this!

[dhruvkb]

For the API repo, I highly recommend using Sphinx + reStructuredText. I've already written some scattered documentation that complies with it and it'd be cool to make that more comprehensive.

[AetherUnbound]

Agreed! I think both that and the catalog would benefit from Sphinx + reST. We might also be able to use something like Swagger with our API, though admittedly I know less about that end of things.

[zackkrida]

The API docs use Redoc / Swagger: https://api.openverse.engineering/v1/

[dhruvkb]

@AetherUnbound fun thing is that we already have drf-yasg set up! The documentation is hardcoded as strings though instead of using docstrings so that can be improved.

[AetherUnbound]

Oops, nevermind! I searched the requirements for Swagger and didn't see anything, I wasn't aware of DRF-YASG haha

[zackkrida]

Since this discussion was born we now have https://docs.openverse.org, improvements to that site are being discussed elsewhere.