What should be included in the API reference documentation?

[zklaus]

Checklist

• I added a descriptive title
• I searched open reports and couldn't find a duplicate

What happened?

We rely on autoapi to turn our docstrings into documentation. From its documentation:

With the default settings, AutoAPI will document everything that is publicly accessible through the actual package when loaded in Python. For example if a function is imported from a submodule into a package then that function is documented in both the submodule and the package.

That means that all private and undocumented things also show up in the documentation. That makes it noisy and harder to find the actually documented pieces, as well as more difficult to identify which crucial pieces would most benefit from adding further documentation.

Agreeing on some fundamental principals (include private things? include special functions?) and reflecting them in the configuration would be an easy thing to do to slim down the api docs.

I think it would be good to start with a few basic decision:

Should the API reference documentation only include public APIs, or also private parts?

What parts of the code base should be considered public?

Additional Context

No response