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:
parent
e947a9dcb0
commit
c6fc1210bf
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue