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.

[AA-Turner]

a bit verbose, and annoying ... would it not be nicer to more generally allow app.add_config_value(.., types=x) to take a TypedDict

I'd posit the opposite view, that using arbitrary dictionaries is a worse experience. It's harder to ensure type safety within Sphinx, and passing (mutable) dicts around is harder to follow than individual keys. I also think the documentation is better for individual options, as we can use .. confval:: directives for each. I also think it provides a nicer migration path for those that will move over from /~https://github.com/sphinx-contrib/apidoc.

A

[chrisjsewell]

Ok @AA-Turner I've changed it to individual options, I still don't really agree, but it's not a hill I want to die on lol

It's harder to ensure type safety within Sphinx, and passing (mutable) dicts around is harder to follow than individual keys.

Well there is no real type safety with app.config.xxx anyway 😅

[AA-Turner]

Thank you!

A

[chrisjsewell]

Cheers!

[djhoese]

Awesome that this package got merged into sphinx! Nice job.

A couple questions and possible bugs:

1. When using sphinxcontrib.apidoc I added a rm -rf source/<my_destination_>/*.rst to my sphinx Makefile clean step. This was needed as otherwise module renames would not get rid of the old generate .rst file. Is there a better suggestion for something like this or is this maybe not needed with this new implementation?
2. Do the paths that exclude_patterns is matching against start with the "path"? So if my path is ../../mypkg then my exclude pattern would need to be (with no wildcards) ../../mypkg/subdir/mymod.py, right?

[chrisjsewell]

I honestly didn't even know about sphinxcontrib.apidoc when I wrote this lol 😅, but yes it integrates with #12448 to replace old files (open bug report if not)

exclude patterns should be absolute or relative to the conf directory

[djhoese]

Ok and if I'm seeing the changes in this PR correctly the default was changed to True for remove old, right? Correct me if not. Now to file a bug for sphinx 8.2.0 using much more memory than 8.1.x...

[chrisjsewell]

feel free to propose any documentation updates to clarify anything

[webknjaz]

A related wish I've had for years is doing this all in-memory: #1139 (comment).