List generic arguments for collections.abc base classes in documentation

[sterliakov]

Documentation

When #123544 lands, we'll have PEP585-related documentation spread even further than before. Deprecated aliases in typing correctly list the generic arguments, but are otherwise undocumented - all such entries boil down to "deprecated in favour of collections.abc.X".

Several relevant changes were discussed along #123523.

There's no direct way for a user to find generic parameters of collections.abc.Generator - they are listed for typing.Generator and in "annotating generators and coroutines" section in typing docs (the latter linked from collections.abc.Generator, though).

I'm certain that generic arguments represent an essential part of class' "signature" - basic amount of information we need to see to use it somehow.

However, collections.abc is not really a type-hinting module, hence providing those signatures there directly can add too much cognitive load.

As of now, my best suggestion is to introduce "Type parameters" section for each generic alias there, like this:

.. class:: Mapping
           MutableMapping

   ABCs for read-only and mutable :term:`mappings <mapping>`.

   Type arguments:

   * ``Mapping[KT, VT_co](Collection[KT])``
   * ``MutableMapping[KT, VT](Mapping[KT, VT])``

cc @AA-Turner and @AlexWaygood - we started this discussion in the PR above.

[AlexWaygood]

I'm certain that generic arguments represent an essential part of class' "signature" - basic amount of information we need to see to use it somehow.

From a typing perspective, I fully agree -- but I'm still a little uncertain about including so many complex type signatures directly in the collections.abc docs. It might be good to open a discussion on Discourse and see if we can brainstorm ways of presenting this information in an accessible way, so that people who aren't interested in typing (or, if they're beginners, possibly aren't even aware of typing) don't get terrified by all this information in the collections.abc docs.

[JelleZijlstra]

I feel we should add this information to the collections.abc docs. While not all users of the collections.abc classes need the type information, a large proportion of users do. The collections.abc docs are fairly brief and a mention of the type parameters would not be overwhelming.

[AlexWaygood]

To be clear, I don't strongly object to adding this information to the collections.abc docs... I'm more worried that this might end up being a controversial change that other people might object to, which is why I suggested increasing the visibility of the proposed change before doing it :-)