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

[JelleZijlstra]

This sets up intersphinx and replaces a few PEP links in typing.rst with intersphinx links to the PEPs.

I'm going to ask in the Python Docs discord whether there are any concerns with enabling intersphinx on the Python docs, and wait for an answer before investing time into replacing the remaining links.

• Issue: Link from typing docs to specific sections in the typing spec #117539

---

📚 Documentation preview 📚: https://cpython-previews--117540.org.readthedocs.build/

[JelleZijlstra]

From Petr's comments on Discord, it appears this may cause issues for redistributors (e.g., Linux distros) because it means that building the docs will require Internet access. I think I'll have to open a discussion on Discuss about it first.

[picnixz]

I can suggest some solutions:

1. Provide a copy of the typing inventory. Internet connection is not needed if you have a local copy of the intersphinx inventory.
2. I'm not sure if you really need the full power of intersphinx since most of the links you are referring to are sections or HTML pages that I doubt would change without you noticing it. For instance, in Sphinx, we have the same issue where we need to refer to the docutils specs but there is no intersphinx support for docutils, so we use sphinx.ext.extlinks instead. However, this is quite fragile against URL changes.

[nineteendo]

Wouldn't it better to convert the pull request back to a draft? GitHub automatically prevents you from merging those.

[encukou]

Since this can break people's build workflows, now -- before the first alpha -- is the best time to do it.
I wouldn't backport it, though.

[nineteendo]

Yeah, it also allows us to link to a specific section, rather than the start of the PEP (e.g. typing.overload).

[JelleZijlstra]

@encukou that's an option, but it would be a shame if we aren't able to make this change in the 3.12 and 3.13 docs. Ideally, we'd have a lot of cross-links to the spec.

Maybe at PyCon I can spend some time trying to figure out a robust solution based on @picnixz's suggestions.

[nineteendo]

If intersphinx is a problem, we could maybe use canonical links for https://typing.readthedocs.io.

[willingc]

Looping back around to this: @JelleZijlstra @encukou Thoughts on next steps now that some time has gone by?

[JelleZijlstra]

I'd like this to happen but I don't know if I'll have time to push for and implement a robust solution. I'd be happy if someone else did, though.

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

[hugovk]

Testing an offline build (having first done make -C Doc clean venv online):

❯ make -C Doc html
mkdir -p build
blurb version 2.0.0
sphinx-build 8.2.3
Building NEWS from Misc/NEWS.d with blurb
PATH=./venv/bin:$PATH sphinx-build --builder html --doctree-dir build/doctrees --jobs auto   --fail-on-warning . build/html
Running Sphinx v8.2.3
loading translations [en]... done
matplotlib is not installed, social cards will not be generated
making output directory... done
loading intersphinx inventory 'typing' from https://typing.python.org/en/latest/objects.inv ...
WARNING: failed to reach any of the inventories with the following issues:
intersphinx inventory 'https://typing.python.org/en/latest/objects.inv' not fetchable due to <class 'requests.exceptions.ConnectionError'>: HTTPSConnectionPool(host='typing.python.org', port=443): Max retries exceeded with url: /en/latest/objects.inv (Caused by NameResolutionError("HTTPSConnection(host='typing.python.org', port=443): Failed to resolve 'typing.python.org' ([Errno 8] nodename nor servname provided, or not known)"))
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 545 source files that are out of date
updating environment: [new config] 545 added, 0 changed, 0 removed
reading sources... [100%] whatsnew/2.1 .. whatsnew/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/hugo/github/python/cpython/main/Doc/howto/argparse.rst: document is referenced in multiple toctrees: ['howto/index', 'library/argparse'], selecting: library/argparse <- howto/argparse
done
preparing documents... done
copying assets...
copying downloadable files... [100%] includes/tzinfo_examples.py
copying static files...
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/basic.css
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/language_data.js
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/documentation_options.js
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/classic.css
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/sidebar.js
copying static files: done
copying extra files...
copying extra files: done
copying assets: done
/Users/hugo/github/python/cpython/main/Doc/library/typing.rst:1729: WARNING: undefined label: 'typing:unpack-kwargs' [ref.ref]
/Users/hugo/github/python/cpython/main/Doc/library/typing.rst:1840: WARNING: undefined label: 'typing:variance' [ref.ref]
/Users/hugo/github/python/cpython/main/Doc/library/typing.rst:2088: WARNING: undefined label: 'typing:typevartuple' [ref.ref]
/Users/hugo/github/python/cpython/main/Doc/library/typing.rst:2248: WARNING: undefined label: 'typing:paramspec' [ref.ref]
writing output... [100%] whatsnew/3.8 .. whatsnew/index
generating indices... genindex py-modindex done
writing additional pages... download index search opensearch done
copying images... [100%] using/win_install_freethreaded.png
dumping search index in English (code: en)... done
dumping object inventory... done
Writing glossary.json
profiling_trace: Injected 38 trace events into profiling-sampling-visualization.js
Linklint: unlinked 3575 refs: 1982 duplicate, 1593 self
build finished with problems, 5 warnings (with warnings treated as errors).
make: *** [build] Error 1

The make command exits with an error -- but that's only because we have SPHINXERRORHANDLING = --fail-on-warning in our Makefile which can be overridden with make -C Doc html SPHINXERRORHANDLING= or by calling sphinx-build directly.

And there's some warnings, but the docs finishing building and things like:

   See :ref:`the typing spec <typing:unpack-kwargs>` for more details on using
   ``Unpack`` for ``**kwargs`` typing.

Render as plain text:

See the typing spec for more details on using Unpack for **kwargs typing.

Which is fine.

But:

      * :ref:`typing:paramspec` -- typing specification for ``ParamSpec``

Renders as:

• typing:paramspec – typing specification for ParamSpec

Instead of:

• ParamSpec – typing specification for ParamSpec

Which isn't as good, but I think this is okay overall. Especially as most people visit http://docs.python.org, and the docs still build and make sense for offline rebuilds that have a much smaller readership.

Alternatively we could bundle the typing intersphinx file in our repo, but I'd prefer not to.

Or we could make a Sphinx extension to handle missing intersphinx and fallback in some other way.