How should we create API documentation?

[caro401]

All of the Python packages associated with Kiara need to have some way of displaying their (internal) API documentation. This means information about the Python classes and functions contained in each package. An example of the existing deployed documentation is here for the tabular plugin.

This documentation is currently generated using Mkdocs and its material theme. The code to do this generation comes from the plugin template here on GitHub, but Markus isn't happy with this in its current state.

Having this documentation hosted somewhere is essential for plugin developers to be able to share how their plugin works. Ideally, we'd make it really easy for plugin developers to create docs sites in the same way that internally-developed plugins do. This probably means we need the API docs to be standalone per plugin, so there's no dependencies on the team doing anything on a central docs site to get this API documentation published. @makkus do you agree?

Whatever approach we go with, we should include code for doing this with the plugin template as we do currently, along with docs for plugin authors on how to publish their own docs.

Open questions I can think of about how we do this:

• do we continue to use the existing mkdocs-material-based template? If so, what and how much work is involved in bringing it to an acceptable standard
• do we instead start from scratch with a different approach? If so, what approach? Common options in the Python ecosystem would be mkdocs with or without material, or something sphinx-based which might then be hosted at readthedocs. I have no up-to-date experience with either.
• what features does this thing need to have? For example, do we care about internationalization or translations? I think not for API docs but maybe. Do we need to provide docs for every published version of a package? Probably? Does it need to have other things like search?

@makkus could you elaborate exactly what problems and shortcomings you see with the current solution, so we can either work out how to fix them, or make sure we don't have the same issues in a different solution

[caro401]

This is currently the lowest priority of docs to work on.

It may be worth considering intentionally keeping these docs somewhere separate from where end-users will be looking for docs (tutorials etc, and the module/operation/datatype docs from #2), since it really doesn't apply to them, or at least making this kind of docs in some sense visually distinct, so end-users can know they don't need to understand everything contained in them.

[makkus]

Yeah, I agree, this is lowest priority. It would be good to have generated API docs, but given how resource constrainted we are...