autodoc: Updating the Developing autodoc extensions example

[LecrisUT]

Is your feature request related to a problem? Please describe. Currently the Developing autodoc extensions is using the legacy interface. It is not clear how one is supposed to do the same with the new interface. Afaict, this is not yet a solved problem right now.

While we are at it, it would be nice to actually clarify:

• What does extending autodoc do and what you can overwrite. The example seems to focus on adding to the contents, but what about other things that you would want to do like changing the signature?
• How does it play with automodule or sphinx-apidoc?
• What are some usecases where you would want to do that? I can imagine it would be useful for dataclasses and equivalents like attrs, pydantic, and those providing appropriate extensions to auto-document?
• Can an object be autodocumented twice (maybe with no-index), once as autoclass in the sphinx-apidoc and once as your custom method somewhere else in your document? Are there pitfalls to be aware of when doing so?

Additional context

• Split off from https://github.com/sphinx-doc/sphinx/pull/14091#issuecomment-3576667738