Add sphinx.ext.apidoc extension

[AA-Turner]

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.

Per the original PR, there is no documentation and two outstanding TODO comments in the PR.

References

• recreation of Allow using sphinx.ext.apidoc as an extension #12471
• 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

cc @chrisjsewell

[timhoffm]

Could this get at least a minimal doc page under https://github.com/sphinx-doc/sphinx/tree/master/doc/usage/extensions?

[AA-Turner]

https://sphinx--13220.org.readthedocs.build/en/13220/usage/extensions/apidoc.html

[timhoffm]

Minor: I would put 'path' first. The module to be documented is the main aspect.

Suggested change

	{'destination': 'source/', 'path': 'path/to/module'},
	{
	'destination': 'source/',
	'path': 'path/to/another_module',
	{'path': 'path/to/module', 'destination': 'source/'},
	{
	'path': 'path/to/another_module',
	'destination': 'source/',

Alternatively, the modules are so prominent that one could make them keys of a dict:

apidoc_modules = {
    'path/to/module': {'destination': 'source/'},
    'path/to/other_module': {
        'destination': 'source/',
        'exclude_patterns': ['**/test*'],
        'maxdepth': 4,
        'followlinks': False,
        'separatemodules': False,
        'includeprivate': False,
        'noheadings': False,
        'modulefirst': False,
        'implicit_namespaces': False,
    },
}

[timhoffm]

On a side note, I could see the case for making config parameters applying to all modules. This would remove the need for repeating a lot of keys for multiple modules.

apidoc_module_config = {
        'followlinks': False,
        'separatemodules': False,
        'includeprivate': False,
        'noheadings': False,
}
apidoc_modules = {
        {'path': 'path/to/module'},
        {'path': 'path/to/other_module'},
        {'path': 'path/to/third_module', 'includeprivate': True}, # overriding global settings
}

Implementation-wise one would just merge the dicts apidoc_module_config and the individual config dicts.

But that could also be added later.

[AA-Turner]

Cc @chrisjsewell -- I just rebased the original PR so would prefer to have your input on larger design changes such as Tim suggests.

[chrisjsewell]

Thanks @AA-Turner I'll have a look in the next few days