Link from typing docs to specific sections in the typing spec

[JelleZijlstra]

The typing docs currently frequently link to the PEPs that defined new typing features. Instead, they should link to the typing spec, which unlike the PEPs is a living document.

In the online documentation, we can do this with intersphinx. I have this running locally and can send a PR.

I'm less sure about how to handle this in the docstrings. For example, Protocol's docstring refers to PEP 544:

cpython/Lib/typing.py

Line 1987 in b32789c

See PEP 544 for details. Protocol classes decorated with

. Should we provide a full URL to the spec, like https://typing.readthedocs.io/en/latest/spec/protocol.html?

Linked PRs

• gh-117539: Link to the Python typing spec in typing docs #117540

[AlexWaygood]

. Should we provide a full URL to the spec, like typing.readthedocs.io/en/latest/spec/protocol.html?

I would just say something like "See the typing spec for more details", I think

[JelleZijlstra]

I would just say something like "See the typing spec for more details", I think

That feels a little unhelpful to users though. It's applicable to every object in the typing module, so it's redundant to put it in every docstring, and the spec is a big document and I'd rather send users to a specific section that is relevant.

[AlexWaygood]

I know what you mean, but raw URLs are ugly in docstrings and likely to go out of date

[alliesw]

"typing.readthedocs.io/en/latest/spec/protocol.html" is terrible to read and people lack patience. It has to be more human readable and simple to tag the URL's as "Learn about the latest typing specs" or simply "Latest Typing Specs".