From c6fc1210bfb97588fb218e2ed30f7c39ba7bb78a Mon Sep 17 00:00:00 2001 From: David Foster Date: Fri, 14 Jun 2024 16:31:40 -0700 Subject: [PATCH] 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> --- peps/pep-0012.rst | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/peps/pep-0012.rst b/peps/pep-0012.rst index 9ca94ed23..cb52ba430 100644 --- a/peps/pep-0012.rst +++ b/peps/pep-0012.rst @@ -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 +`_ +to other Sphinx sites, +such as the `Python documentation `_ +`packaging.python.org `_, +and `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 ` + + +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 -`_ -to other Sphinx sites, -currently the `Python documentation `_ -and `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