DOCS: Adopt autoapi v3 for our API doc generation.

[tkknight]

📚 Documentation

We currently use apidoc for our API Docs, which look like this: https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html.

Autodoc headline:

Sphinx AutoAPI is a Sphinx extension for generating complete API documentation without needing to load, run, or import the project being documented.

In contrast to the traditional Sphinx autodoc, which requires some manual authoring and uses code imports, AutoAPI finds and generates documentation by parsing source code.

I have locally trialed using autoapi which generally is:

• presented better
• uses the autosummary for modules and classes (table summary)

There is a build warning that can be resolved with some investigation but the main issue blocking the adoption is the use of inline comments to document attributes using #: str: this is a comment before the attribute is defined. autoapi works using the triple quotes after the attribute is defined but this would mean changing lots of comments already present and it is limited to a single line.

Lets watch readthedocs/sphinx-autoapi#344 to see if support for #: comments is added, if so we can look at adopting autoapi.

[bjlittle]

@tkknight Should this pull-request be in draft?

[bjlittle]

@tkknight doh! my mistake, this is an issue, all good 😆