Issue 40979: typing module docs: keep text, add subsections

The typing module documentation page has a very long section "Classes, functions, and decorators" (https://docs.python.org/3/library/typing.html#classes-functions-and-decorators) that should be split in subsections. The ordering of the entries seems haphazard: it's not alphabetical. Its grouped according to invisible categories. 

The categories appear as comments in the source code of typing.py: the `__all__` global lists the API split into categories (see below). We should add these categories to the page as subsections of "Classes, functions, and decorators"

- Super-special typing primitives.
- ABCs (from collections.abc).
- Structural checks, a.k.a. protocols.
- Concrete collection types.

Would you care to submit a PR?

Thanks, I am happy to submit a PR. Before I do, I'd like to discuss the subsection titles, starting from the arrangement in typing.__all__:


# Special typing constructs (source comment is: "Super-special typing primitives")
Any Callable ClassVar Final ForwardRef Generic Literal Optional Protocol Tuple Type TypeVar Union 

In this section I propose we add:

- NamedTuple and TypedDict: source comments say "Not really a type" (for both), and I believe it's confusing to list them along the other collections. Tuple is already in the "Special constructs" category, so NamedTuple should follow in there. TypedDict is very different from the other collections, it's purely a type hinting construct with no runtime counterpart so it's pretty special IMHO.

- AnyStr: should be listed right after TypeVar, NoReturn, NewType

- Text, TYPE_CHECKING: I am not sure about those, but if they are removed from the "One-off things" all that remains are functions and decorators, which looks good.


# ABCs (from collections.abc) [Keep this title]
AbstractSet ByteString Container ContextManager Hashable ItemsView Iterable Iterator KeysView Mapping MappingView MutableMapping MutableSequence MutableSet Sequence Sized ValuesView Awaitable AsyncIterator AsyncIterable Coroutine Collection AsyncGenerator AsyncContextManager

# Concrete collection types [keep this title]
ChainMap Counter Deque Dict DefaultDict List OrderedDict Set FrozenSet 

- Generator should go with "ABCs"
- NamedTuple TypedDict should go with "Special typing constructs"

 
# Protocols (source comment is "Structural checks, a.k.a. protocols.")
Reversible SupportsAbs SupportsBytes SupportsComplex SupportsFloat SupportsIndex SupportsInt SupportsRound


# Functions and decorators (source comment is "One-off things.")
cast final get_args get_origin get_type_hints no_type_check no_type_check_decorator  overload runtime_checkable 

- AnyStr NewType NoReturn: these should go with "Special typing constructs"

- Text TYPE_CHECKING: either go with "Special typing constructs" or a constants section, which could include AnyStr as well

There are also the IO and re types which could have their own subsections.

Looking forward for feeback on this. Thanks!

Sorry, there was an editing mistake above.

Where I wrote:


- AnyStr: should be listed right after TypeVar, NoReturn, NewType

I meant to write:

- AnyStr: should be listed right after TypeVar
- NoReturn, NewType: both belong with "Special Constructs" as well
- Text, TYPE_CHECKING: I am not sure about those ...

This is my proposal for sections to replace the existing "Classes, functions, and decorators" section. The names are sorted within each section.

# Special typing primitives	
	Any
	Callable
	ClassVar
	ForwardRef
	Generic
	Literal
	NamedTuple
	NewType
	NoReturn
	Optional
	Type
	TypedDict
	TypeVar
	Union

# Generic ABCs	
	AbstractSet
	AsyncContextManager
	AsyncGenerator
	AsyncIterable
	AsyncIterator
	Awaitable
	ByteString
	Collection
	Container
	ContextManager
	Coroutine
	Generator
	Hashable
	io.IO
	io.BytesIO
	io.TextIO
	ItemsView
	Iterable
	Iterator
	KeysView
	Mapping
	MappingView
	MutableMapping
	MutableSequence
	MutableSet
	re.Pattern
	re.Match
	Sequence
	Sized
	ValuesView	

# Generic Concrete Collections	
	ChainMap
	Counter
	DefaultDict
	Deque
	Dict
	FrozenSet
	List
	OrderedDict
	Set
	Tuple

# Structural checks, a.k.a. protocols.	
	Reversible
	SupportsAbs
	SupportsBytes
	SupportsComplex
	SupportsFloat
	SupportsInt
	SupportsRound	

# Functions and decorators	
	cast
	final
	get_args
	get_origin
	get_type_hints
	no_type_check
	no_type_check_decorator
	overload
	runtime_checkable
	type_check_only
	
# Aliases and constants	
	AnyStr
	Text
	TYPE_CHECKING

Reviewers, besides adding section titles and reordering the entries, I made only these changes to the text:

- entry for IO, TextIO, BinaryIO: added sentence "These types are in the ``typing.io`` namespace."

- entry for Pattern, Match: added sentence "These types are in the ``typing.re`` namespace."

- entry for TypedDict: removed the words "equivalent to" from the sentence "At runtime it is <equivalent to> a plain dict."

This organization makes good sense to me.   Hopefully, we can get Guido and Ivan to take a look at it.

FWIW I like Guido's suggestion in the PR, I would rather use "importance order" than alphabetical order.

I have incorporated Guido's suggestions and added additional subsections to make it easier to navigate the page.

I also added notes that fix the issue https://bugs.python.org/issue40978 — "Document that typing.SupportsXXX protocols are runtime checkable"

New changeset ab72fdeb82c3ab045b480cd4bb4f928c12653ecb by Luciano Ramalho in branch 'master':
bpo-40979: refactored typing.rst; (mostly) same content, new sub-sections and ordering (#21574)
https://github.com/python/cpython/commit/ab72fdeb82c3ab045b480cd4bb4f928c12653ecb

Thank you so much for your hard work and flexibility! The chapter is in much better shape now.

New changeset b3ad2ca56afc6a56c9a6e7b419bc05e8e5b15e19 by Guido van Rossum in branch '3.9':
[3.9] bpo-40979: refactored typing.rst; (mostly) same content, new sub-sections and ordering (GH-21574) (#21843)
https://github.com/python/cpython/commit/b3ad2ca56afc6a56c9a6e7b419bc05e8e5b15e19

stage: patch review -> resolved

pull_requests: + pull_request20717
stage: patch review