Integrate the Type Stubs document into the spec

[srittau]

The Type Stubs document (source/stubs.rst) is based on a proposed PEP by @rchen152, @JelleZijlstra, @Solumin, and myself to describe the allowed elements of type stubs. It was turned into kind of a proto-spec document, instead of a PEP. I haven't reviewed it in detail, but I think at least the "spec" parts of this document should be moved to the spec: chapters "Syntax" and "Supported Constructs". They might need updating, though. The "Distribution" chapter is mostly redundant with the spec anyway. The other chapters should probably moved to other documents, like "Writing and Maintaining Stub Files".

[JelleZijlstra]

Agree that the sections you flagged should be incorporated into the spec, with some updates.

For example, the "Syntax" section says stubs should follow 3.7 syntax, but 3.7 is dead now; we should instead say stubs should follow the syntax of the earliest Python version that is not EOL yet.

[rchen152]

I'd like to take a stab at this, if that's okay.

[erictraut]

Thanks for volunteering, @rchen152.

There's overlap between the Type Stubs document and the Typing Python Libraries document. I'd love to see these unified when this content is added to the typing spec.