Restore the legacy implementation of autodoc for compatibility

[AA-Turner]

Copied from their state as at 58293c2, with duplication removed where possible.

References

• Make autodoc more maintainable #13751
• TRACKING: Problems in the new implementation of autodoc #14089

[LecrisUT]

Could we at least get the documentation/example to work with the non-legacy interface? Afaiu with the new API, the directive is more free-formed and for non-python documenters I think it would be fine because it would be a clearer sign of something like "we do not do anything special, just make sure you create the content appropriately", but the example is more focused on extending specifically python documenters (PS: I think an example with @dataclass would be really useful) and that one is quite unclear how to link it to the automodule.

Also is the new interface locked now, or would you wait for additional feedback from the developers that are trying to migrate to finalize it in 9.1? I would have one request to add to the interface: that is to move it in the python domain in order to avoid conflicts with other domains that use the same automodule naming. I guess that one requires some interface to inject additional directives in a domain?

[AA-Turner]

@LecrisUT

Could we at least get the documentation/example to work with the non-legacy interface?

What I'm missing at the moment is an understanding of what/where autodoc extensions need to act. My two current thoughts are allowing subclassing of _ItemProps or adding more autodoc events.

Afaiu with the new API, the directive is more free-formed and for non-python documenters I think it would be fine because it would be a clearer sign of something like "we do not do anything special, just make sure you create the content appropriately",

I don't really understand what you mean by "non-Python documenters". The autodoc extension only works with Python code by design, it does not support any other programming language.

but the example is more focused on extending specifically python documenters ... and that one is quite unclear how to link it to the automodule.

Per above, I don't follow here.

Also is the new interface locked now, or would you wait for additional feedback from the developers that are trying to migrate to finalize it in 9.1? I would have one request to add to the interface: that is to move it in the python domain in order to avoid conflicts with other domains that use the same automodule naming. I guess that one requires some interface to inject additional directives in a domain?

Again, sphinx.ext.autodoc is Python-only. It produces directives for the Python domain (see _renderer). Can you open a new issue fully detailing your use case and concerns? I think this might be an X-Y problem.

A