Move typing-related usage of PEP585 generics from `typing` docs to `collections.abc`

[sterliakov]

Documentation

As pointed out in #123521, currently we have typing-related usage of PEP585 generics (Generator, Callable, Coroutine, etc.) explained on typing page. However, those aliases are deprecated, and there's no backlink from their collections.abc counterparts.

So, currently all users of the recommended modern option (collections.abc generics) have no documentation regarding their use in typing context at hand. Worse, classes there don't even have their generic arguments listed - only the name:

class collections.abc.Generator

This clearly should be fixed. At minimum the following needs to hold:

• collections.abc aliases have their generic arguments listed in the docs
• All typing-related info from corresponding typing docs entries should be reachable from collections.abc docs.

Upon some thinking I agree with @ZeroIntensity that moving all information to collections.abc and only retaining deprecation warning with a link in typing docs could be the most ergonomic option.

Linked PRs

• gh-123523: Rework typing documentation for generators and coroutines, and link to it from collections.abc docs #123544
• [3.13] gh-123523: Rework typing documentation for generators and coroutines, and link to it from collections.abc docs (GH-123544) #123790
• [3.12] gh-123523: Rework typing documentation for generators and coroutines, and link to it from collections.abc docs (#123544) #123792

[ZeroIntensity]

@JelleZijlstra, as a typing expert, does this approach seem good to you?

[AA-Turner]

As a user of collections generics, this would be quite useful, and seems appropriate now that Python 3.8 is nearing end-of-life. Happy to defer to others' views, though.

A

[sterliakov]

I think +3 on the last comment is a good enough indicator - I'll grab this and open a PR soon.