Merge typeshed style guide w/ official typing docs?

[yangdanny97]

I see that contributing.md has a style guide for stubs, which somewhat duplicates the documentation on Writing and Maintaining Stubs on the official typing docs.

Should we reduce duplication by linking to the latter from the former? There might be a few extra typeshed-specific things, but for general style stuff I don't see why we need to write it all out again here.

[JelleZijlstra]

Yes, we should point people to the typing docs, and only add typeshed-specific guidance where it's different from the general guide.

[srittau]

In fact, the current style guide from the typing docs was originally copied from typeshed. But due to the limbo that the stubs PEP – which ultimately became part of the docs – was in for a long time, the removal of the advice from the typeshed docs never happened. Most advice from CONTRIBUTING probably needs to be merged into the typing docs and then CONTRIBUTING needs slimming down.

[yangdanny97]

I can take a stab at merging these docs.

The instructions on how to handle disagreement between docs and implementation seems to differ between the two docs.

CONTRIBUTING.md says to follow the implementation over the docs, while the typing guide just says to use your best judgement about intent.

https://github.com/python/typeshed/blob/main/CONTRIBUTING.md#what-to-do-when-a-projects-documentation-and-implementation-disagree

https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#documentation-or-implementation

[yangdanny97]

For the other stuff, made a PR here: https://github.com/python/typing/pull/1882

There are a few typeshed-specific sections that probably need to remain:

• Incomplete annotations
• Any vs Incomplete
• The Any trick

[yangdanny97]

The guide to remove docstrings for conciseness seems to conflict with Pyright's advice here: https://microsoft.github.io/pyright/#/typed-libraries?id=inlined-type-annotations-and-type-stubs

Not sure how/if we should align that.