Automatic annotations break with autosummary about sphinxcontrib-trio

[njsmith]

Would it be easy to post a tiny working example?

[Fuyukai]

https://github.com/SunDwarf/sphinxcontrib-trio-issue-8
This should be all that's need to show the issue. Just pipenv install; cd docs; make html.

Notice the missing await at the beginning of test_one despite it being an async function. The trio docs don't have this issue, despite using autodoc.

[njsmith]

Ughhhh sphiiinnnnx.

sphinx.ext.autosummary has a helper script to generate new .rst files on the fly. It's written as a standalone script, sphinx/ext/autosummary/generate.py. So it can't assume that it's run inside a normal sphinx environment – but it wants to use autodoc functionality anyway. So at import time, it attempts to set up a fake autodoc environment, by manually registering all the normal autodoc classes.

The sphinx.ext.autosummary extension has a callback for the sphinx build-inited event, which calls sphinx.ext.autosummary.process_generate_options. Then process_generate_options imports sphinx.ext.autosummary.generate. So at some point after sphinx's initial configuration is read and all plugins – like sphinxcontrib-trio are loaded – we end up running the code in generate.py to set up the fake autodoc environment, and since we're doing this inside the real sphinx process, it ends up overwriting the normal autodoc environment. And in particular it overwrites sphinxcontrib-trio's customized autofunction/automethod directives.

sphinxcontrib-asyncio is spared, because of a confusing thing where you can have multiple autodoc classes registered to provide documentation for, say, functions, and they're selected based on their .priority attributes. But each such class has an associated directive name, and you can't have multiple autodoc classes registered with the same directive name at the same time. sphinxcontrib-trio takes over the regular automethod and autofunction directives, so its classes get lost when the default classes are reloaded; sphinxcontrib-asyncio uses autocomethod and autocofunction directives, so they survive.

It looks like this was already fixed in 1.7, sort of accidentally in passing – in addition to other changes, this commit moves the fake autodoc setup code so that it's called from main rather than at import time: sphinx-doc/sphinx@5d6413b

In the mean time, there's a silly but simple fix: we can import sphinx.ext.autosummary.generate ourselves up front, to get all the import side-effects out of the way before we register our autodoc classes.