Add api docs

[bdraco]

What do these changes do?

Add API docs

Are there changes in behavior for the user?

no

[webknjaz]

@bdraco would you want to integrate sphinxcontrib.apidoc instead of authoring these in separate documents? Here's a configuration example: https://github.com/ansible/awx_plugins.interfaces/blob/devel/docs/conf.py#L126-L138. You basically add a dep, add it to the extensions, make a gitignored folder and include that in the index file. And it builds the pages from docstrings.

[webknjaz]

Oh.. That might be problematic for the C-extensions, though.

[bdraco]

@bdraco would you want to integrate sphinxcontrib.apidoc instead of authoring these in separate documents? Here's a configuration example: ansible/awx_plugins.interfaces@devel/docs/conf.py#L126-L138. You basically add a dep, add it to the extensions, make a gitignored folder and include that in the index file. And it builds the pages from docstrings.

Oh.. That might be problematic for the C-extensions, though.

I think that makes sense if we end up adding more here. I'm not really expecting this module will be all that active though.

[webknjaz]

@bdraco I've enabled the PR builds in RTD, apparently, that checkbox wasn't selected.

[Dreamsorcerer]

@bdraco would you want to integrate sphinxcontrib.apidoc instead of authoring these in separate documents? Here's a configuration example: https://github.com/ansible/awx_plugins.interfaces/blob/devel/docs/conf.py#L126-L138. You basically add a dep, add it to the extensions, make a gitignored folder and include that in the index file. And it builds the pages from docstrings.

I've been meaning to ask if there was a reason we've not done that in any of our projects. We often seem to end up with docs getting a little out-of-sync because they're written manually.

[bdraco]

I think yarl is a great place to start with this approach as it has a lot of methods and it’s likely to be a lot more active than this lib

[webknjaz]

@bdraco would you want to integrate sphinxcontrib.apidoc instead of authoring these in separate documents? Here's a configuration example: ansible/awx_plugins.interfaces@devel/docs/conf.py#L126-L138. You basically add a dep, add it to the extensions, make a gitignored folder and include that in the index file. And it builds the pages from docstrings.

I've been meaning to ask if there was a reason we've not done that in any of our projects. We often seem to end up with docs getting a little out-of-sync because they're written manually.

@Dreamsorcerer yeah, I've looked into it a couple of times in the past actually, just forgot :)
The main problem is that the C-extensions aren't inspectable by Sphinx IIRC (there was an upstream bug somewhere). I don't remember if this can be addressed with some stubs like pyi.
Another issue was that Andrew didn't want the docstrings to be big (but I think we last talked about that over 7 years ago). He was also concervative when I brought up the suggestion to auto-include parts README (and other docs that render on GH too) into Sphinx docs to avoid duplication, like I do in all my other projects. I've since seen some mentions that some projects (CPython maybe?) were migrating away from in-docstring docs because it was hurting the readabiliy. But personally, I'm very much in favor of automating stuff.

[webknjaz]

I think yarl is a great place to start with this approach as it has a lot of methods and it’s likely to be a lot more active than this lib

On the contrary, I'd start with a low-traffic lib where experiments could happen in a safe setting, before scaling to places that would require more integration work that might not pay off because of some limitations.