API Docs

[ZanSara]

As discussed in https://github.com/ManderaGeneral/generalimport/issues/18, we could add auto-generated API docs to this project.

As done for Canals, I recommend using MkDocs (the Material theme is especially featureful) and host the result on GitHub Pages. It's generally very simple, and as long as the docstrings are well formatted with the Google style (see this SO answer) it's maintenance-free. Such docs can be fully automated with a simple GitHub workflow on every push to master.

MkDocs has great documentation, and in case of need an example of how to do create and deploy these API docs can be seen in Canals: the configuration lives in mkdocs.yml (made a bit complex by the mermaid support), the docs are found in the docs folder, and here is the workflow that deploys the docs.

[Mandera]

Sounds great! A bit overwhelming since I've never tried it though.

I've been using the reST style docstrings. Is that something we could convert to Google style with black https://github.com/ManderaGeneral/generalimport/issues/23?

I do love mermaid so that sounds worth it!

Perhaps we'll only do this with generalimport to begin with, in a separate workflow file for now

[ZanSara]

I can totally help if you need! It was also the first time I used all of this in Canals and it was way more straightforward than I expected :slightly_smiling_face:

I've been using the reST style docstrings. Is that something we could convert to Google style with black https://github.com/ManderaGeneral/generalimport/issues/23?

No, but you can probably use https://github.com/cbillingham/docconvert for the task. That would need to run just once and then once you commit the changes it should be good to go.