PEP 12: Extract Intersphinx section. Add example of Intersphinx reference. (#3827)

* PEP 12: Extract Intersphinx section. Add example of Intersphinx reference.

* Update peps/pep-0012.rst

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

---------

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
This commit is contained in:
David Foster 2024-06-14 16:31:40 -07:00 committed by GitHub
parent e947a9dcb0
commit c6fc1210bf
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 21 additions and 11 deletions

View File

@ -647,8 +647,27 @@ If you find that you need to use a backslash in your text, consider
using inline literals or a literal block instead.
Canonical Documentation and Intersphinx
---------------------------------------
Intersphinx
-----------
You can use
`Intersphinx references
<https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_
to other Sphinx sites,
such as the `Python documentation <https://docs.python.org/>`_
`packaging.python.org <https://packaging.python.org/>`_,
and `typing.readthedocs.io <https://typing.readthedocs.io/>`_,
to easily cross-reference pages, sections and Python/C objects.
For example,
to create a link pointing to a section of the typing docs,
you would write the following::
:ref:`type expression <typing:type-expression>`
Canonical Documentation
-----------------------
As :pep:`PEP 1 describes <1#pep-maintenance>`,
PEPs are considered historical documents once marked Final,
@ -659,15 +678,6 @@ or an appropriate subclass:
* ``canonical-pypa-spec`` for packaging standards
* ``canonical-typing-spec`` for typing standards
Furthermore, you can use
`Intersphinx references
<https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_
to other Sphinx sites,
currently the `Python documentation <https://docs.python.org/>`_
and `packaging.python.org <https://packaging.python.org/>`_,
to easily cross-reference pages, sections and Python/C objects.
This works with both the "canonical" directives and anywhere in your PEP.
Add the directive between the headers and the first section of the PEP
(typically the Abstract)
and pass as an argument an Intersphinx reference of the canonical doc/spec