I’m proposing to merge the Type Stubs doc into the rest of the typing documentation: pull request here. This moves the specification-like sections into the spec and the rest of the content into the “Writing and Maintaining Stub Files” guide, making the documentation around stub files more cohesive.
Most of the content is substantially unchanged. I made a few updates to things that were clearly out-of-date (see PR description).
I’ve made significant updates to this pull request based on feedback from @srittau, @erictraut, and others. In particular, guidance for stub authors has been split off into separate PRs, redundant sections have been removed, the “Supported Constructs” section has been rewritten to focus on what type checkers should do, and the “Library Interface” section from the “Typing Python Libraries” guide has been incorporated. Feedback welcome here.
The Typing Council has accepted this change.