python
gh-117539: Link to the Python typing spec in typing docs
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: gh-117539
📚 Documentation preview 📚: https://cpython-previews--117540.org.readthedocs.build/
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.
I can suggest some solutions:
- Provide a copy of the typing inventory. Internet connection is not needed if you have a local copy of the intersphinx inventory.
- 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.
Wouldn't it better to convert the pull request back to a draft? GitHub automatically prevents you from merging those.
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.
Yeah, it also allows us to link to a specific section, rather than the start of the PEP (e.g. typing.overload).
@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.
If intersphinx is a problem, we could maybe use canonical links for https://typing.readthedocs.io.