Add sphinx.ext.apidoc extension

[chrisjsewell]

Purpose

A common use-case is that users simply want to point Sphinx towards a Python module, and have it generate documentation automatically.

This is not possible currently, without a "pre-build" step of running the sphinx-autogen CLI.

This PR adds sphinx.ext.apidoc as a sphinx extension, to incorporate the source file generation into the sphinx build.

https://sphinx--13333.org.readthedocs.build/en/13333/usage/extensions/apidoc.html#module-sphinx.ext.apidoc

References

• sphinx-build should auto-generate autodoc/summary rst files that can be customized using a Python callback #6829
• Sphinx apidoc extension #4101
• https://github.com/sphinx-contrib/apidoc
• Allow using sphinx.ext.apidoc as an extension #12471
• Add sphinx.ext.apidoc extension #13220

[chrisjsewell]

In addition to #12471 and #13220 this adds the apidoc_defaults config and a changelog entry

[AA-Turner]

Feel free to push to the original PR branch in the future instead of opening a replacement PR, makes it easier to keep all review comments in the same place!

[AA-Turner]

apidoc_defaults

Would you oppose splitting these out to one configuration option per default value? It's easier for typing and documentation to be more granular, but it is more verbose. This is also the approach taken by https://github.com/sphinx-contrib/apidoc.

A

[chrisjsewell]

Would you oppose splitting these out to one configuration option per default value? It's easier for typing and documentation to be more granular, but it is more verbose.

so like apidoc_default_maxdepth, apidoc_default_followlinks, ...?

yeh err it is a bit verbose, and annoying to code 😅

thinking out loud; would it not be nicer to more generally allow app.add_config_value(.., types=x) to take a TypedDict, and modify check_confval_types to check against it?
This would be helpful for numerous core/extension configs.