Expand documentation for integrating type stubs into existing code bases

[kkirsche]

On https://typing.readthedocs.io/en/latest/index.html there are various sections to help users find tools such as type checkers, linters and formatters, and development environments with type support.

I had previously asked in python/typeshed#8482 how would a user go about integrating existing type stubs into their application. This may be due to a third party or typeshed having created stubs either because the type hints were missing in a library or the provided type information was sufficiently inaccurate to encourage the user to take this type of action.

The team was kind enough to suggest various tools to assist with addressing this problem, and I was wondering if there was an appetite by the team here to incorporate a new "Type Stub Integration" section (or a different proposed name) to the Typing-Related Tools section?

[hauntsaninja]

I would love that!

Two quick thoughts:

• I'd be happy to add either a new page on "Integrating types from stubs", or expanding the scope of https://typing.readthedocs.io/en/latest/source/writing_stubs.html to "Writing, maintaining and integrating stub files". Feel free to go with your best judgement (assuming no one else expresses an opinion)
• One pitfall I found myself doing when contributing here is slowly recreating documentation for a specific tool. This should be avoided; for example, see ^ where we keep things brief and try to defer to each tool's own documentation

[kkirsche]

I think it'd be great to potentially do both: first, create a section which provides a simple index of tools as a foundation, and then we can investigate the first bullet more as I expect that will be more involved

I can certainly understand that second point, but I think the challenge is that it shouldn't be so abstract that users don't have a recommended approach or tool. I'd argue that having a canonical tool, whichever that actually is, would be beneficial, especially for beginners / new typing users.

[kkirsche]

Issue renamed to expanding documentation for integrating type stubs into a codebase as the new section has been merged but I don't want to lose hauntsaninja's comment about expanding the documentation around this.