From ba4cb832cd2a87948df8c76b5c66155f0cc658cb Mon Sep 17 00:00:00 2001 From: David Foster Date: Fri, 31 May 2024 09:29:40 -0400 Subject: [PATCH 1/2] PEP 12: Extract Intersphinx section. Add example of Intersphinx reference. --- 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 8f684fdf0f1..e3b31720719 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, +currently 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 From 6fd488d99846e78e68322fcee476d30a719b70d8 Mon Sep 17 00:00:00 2001 From: David Foster Date: Fri, 7 Jun 2024 08:28:24 -0400 Subject: [PATCH 2/2] Update peps/pep-0012.rst Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- peps/pep-0012.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0012.rst b/peps/pep-0012.rst index e3b31720719..5f0ec7ed2de 100644 --- a/peps/pep-0012.rst +++ b/peps/pep-0012.rst @@ -654,7 +654,7 @@ You can use `Intersphinx references `_ to other Sphinx sites, -currently the `Python documentation `_ +such as the `Python documentation `_ `packaging.python.org `_, and `typing.readthedocs.io `_, to easily cross-reference pages, sections and Python/C objects.