From e67494668426520038bb9dfb7a0aa3ff3d77e790 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Sun, 10 Dec 2023 13:19:01 +0200 Subject: [PATCH 1/6] PEP 612: Mark as Final --- peps/pep-0612.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/peps/pep-0612.rst b/peps/pep-0612.rst index a5c51d3a002..d90f890b291 100644 --- a/peps/pep-0612.rst +++ b/peps/pep-0612.rst @@ -4,14 +4,14 @@ Author: Mark Mendoza Sponsor: Guido van Rossum BDFL-Delegate: Guido van Rossum Discussions-To: typing-sig@python.org -Status: Accepted +Status: Final Type: Standards Track Topic: Typing -Content-Type: text/x-rst Created: 18-Dec-2019 Python-Version: 3.10 Post-History: 18-Dec-2019, 13-Jul-2020 +.. canonical-doc:: :external+python:class:`typing.ParamSpec` Abstract -------- From a18dfb31a78f5a45f2b663941bf5e53b47be1b22 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Sun, 10 Dec 2023 15:15:29 +0200 Subject: [PATCH 2/6] PEP 612: also link to typing.Concatenate --- peps/pep-0612.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/peps/pep-0612.rst b/peps/pep-0612.rst index d90f890b291..d07f82a65f3 100644 --- a/peps/pep-0612.rst +++ b/peps/pep-0612.rst @@ -11,7 +11,8 @@ Created: 18-Dec-2019 Python-Version: 3.10 Post-History: 18-Dec-2019, 13-Jul-2020 -.. canonical-doc:: :external+python:class:`typing.ParamSpec` +.. canonical-doc:: :external+python:class:`typing.ParamSpec` and + :external+python:data:`typing.Concatenate` Abstract -------- From 8798fa886e5a6af03ff2f6c375b8e49ef4183beb Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 9 Jan 2024 17:42:46 +0200 Subject: [PATCH 3/6] Link to typing spec as canonical docs --- .../PULL_REQUEST_TEMPLATE/Mark a PEP Final.md | 4 ++- pep_sphinx_extensions/__init__.py | 2 ++ .../parsing/pep_banner_directive.py | 26 +++++++++++++++++-- peps/conf.py | 1 + peps/pep-0012.rst | 2 +- peps/pep-0612.rst | 5 ++-- 6 files changed, 34 insertions(+), 6 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/Mark a PEP Final.md b/.github/PULL_REQUEST_TEMPLATE/Mark a PEP Final.md index 25463c773a3..cc667804f70 100644 --- a/.github/PULL_REQUEST_TEMPLATE/Mark a PEP Final.md +++ b/.github/PULL_REQUEST_TEMPLATE/Mark a PEP Final.md @@ -9,4 +9,6 @@ If you're unsure about something, just leave it blank and we'll take a look. * [ ] Any substantial changes since the accepted version approved by the SC/PEP delegate * [ ] Pull request title in appropriate format (``PEP 123: Mark Final``) * [ ] ``Status`` changed to ``Final`` (and ``Python-Version`` is correct) -* [ ] Canonical docs/spec linked with a ``canonical-doc`` directive (or ``canonical-pypa-spec``, for packaging PEPs) +* [ ] Canonical docs/spec linked with a ``canonical-doc`` directive + (or ``canonical-pypa-spec`` for packaging PEPs, + or ``canonical-typing-spec`` for typing PEPs) diff --git a/pep_sphinx_extensions/__init__.py b/pep_sphinx_extensions/__init__.py index 8538b838a98..f3aaa8ea858 100644 --- a/pep_sphinx_extensions/__init__.py +++ b/pep_sphinx_extensions/__init__.py @@ -73,6 +73,8 @@ def setup(app: Sphinx) -> dict[str, bool]: "canonical-doc", pep_banner_directive.CanonicalDocBanner) app.add_directive( "canonical-pypa-spec", pep_banner_directive.CanonicalPyPASpecBanner) + app.add_directive( + "canonical-typing-spec", pep_banner_directive.CanonicalTypingSpecBanner) # Register event callbacks app.connect("builder-inited", _update_config_for_builder) # Update configuration values for builder used diff --git a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py index 6b247bcc5d7..dfc87c4559c 100644 --- a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py +++ b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py @@ -6,6 +6,7 @@ from docutils.parsers import rst PYPA_SPEC_BASE_URL = "https://packaging.python.org/en/latest/specifications/" +TYPING_SPEC_BASE_URL = "https://typing.readthedocs.io/en/latest/spec/" class PEPBanner(rst.Directive): @@ -24,7 +25,6 @@ class PEPBanner(rst.Directive): admonition_class = nodes.important css_classes = [] - def run(self) -> list[nodes.admonition]: if self.arguments: @@ -81,7 +81,6 @@ class CanonicalDocBanner(PEPBanner): css_classes = ["canonical-doc", "sticky-banner"] - class CanonicalPyPASpecBanner(PEPBanner): """Insert a specialized admonition for PyPA packaging specifications.""" @@ -103,3 +102,26 @@ class CanonicalPyPASpecBanner(PEPBanner): admonition_class = nodes.attention css_classes = ["canonical-pypa-spec", "sticky-banner"] + + +class CanonicalTypingSpecBanner(PEPBanner): + """Insert a specialized admonition for the typing specification.""" + + admonition_pre_template = ( + "This PEP is a historical document. " + "The up-to-date, canonical spec, {link_content}, is maintained on " + f"the `typing specs site <{TYPING_SPEC_BASE_URL}>`__." + ) + admonition_pre_text = ( + "This PEP is a historical document. " + "The up-to-date, canonical specifications are maintained on " + f"the `typing specs site <{TYPING_SPEC_BASE_URL}>`__." + ) + admonition_post_text = ( + "See the `typing specification update process " + "`__ " + "for how to propose changes." + ) + admonition_class = nodes.attention + + css_classes = ["canonical-typing-spec", "sticky-banner"] diff --git a/peps/conf.py b/peps/conf.py index 09b9b3ed3f0..d8e851a5035 100644 --- a/peps/conf.py +++ b/peps/conf.py @@ -52,6 +52,7 @@ intersphinx_mapping = { 'python': ('https://docs.python.org/3/', None), 'packaging': ('https://packaging.python.org/en/latest/', None), + 'typing': ('https://typing.readthedocs.io/en/latest/', None), 'devguide': ('https://devguide.python.org/', None), 'py3.11': ('https://docs.python.org/3.11/', None), 'py3.12': ('https://docs.python.org/3.12/', None), diff --git a/peps/pep-0012.rst b/peps/pep-0012.rst index 073a74dc015..f4a12034148 100644 --- a/peps/pep-0012.rst +++ b/peps/pep-0012.rst @@ -653,7 +653,7 @@ Canonical Documentation and Intersphinx As :pep:`PEP 1 describes <1#pep-maintenance>`, PEPs are considered historical documents once marked Final, and their canonical documentation/specification should be moved elsewhere. -To indicate this, use the ``canonical-docs`` directive +To indicate this, use the ``canonical-doc`` directive or an appropriate subclass (currently ``canonical-pypa-spec`` for packaging standards). diff --git a/peps/pep-0612.rst b/peps/pep-0612.rst index d07f82a65f3..ee13e9e97fc 100644 --- a/peps/pep-0612.rst +++ b/peps/pep-0612.rst @@ -11,8 +11,9 @@ Created: 18-Dec-2019 Python-Version: 3.10 Post-History: 18-Dec-2019, 13-Jul-2020 -.. canonical-doc:: :external+python:class:`typing.ParamSpec` and - :external+python:data:`typing.Concatenate` +.. canonical-typing-spec:: :ref:`typing:paramspec` + +:) Abstract -------- From 234b9ab31503abda76485175c2884d4a29050802 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 9 Jan 2024 17:49:54 +0200 Subject: [PATCH 4/6] Add canonical-typing-spec --- peps/pep-0012.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/peps/pep-0012.rst b/peps/pep-0012.rst index f4a12034148..8f684fdf0f1 100644 --- a/peps/pep-0012.rst +++ b/peps/pep-0012.rst @@ -654,8 +654,10 @@ As :pep:`PEP 1 describes <1#pep-maintenance>`, PEPs are considered historical documents once marked Final, and their canonical documentation/specification should be moved elsewhere. To indicate this, use the ``canonical-doc`` directive -or an appropriate subclass -(currently ``canonical-pypa-spec`` for packaging standards). +or an appropriate subclass: + +* ``canonical-pypa-spec`` for packaging standards +* ``canonical-typing-spec`` for typing standards Furthermore, you can use `Intersphinx references From af171f24fcce059ed6876510b01db5bb20b13b9d Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 9 Jan 2024 17:50:51 +0200 Subject: [PATCH 5/6] Remove debug :) --- peps/pep-0612.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/peps/pep-0612.rst b/peps/pep-0612.rst index ee13e9e97fc..78aac53b30c 100644 --- a/peps/pep-0612.rst +++ b/peps/pep-0612.rst @@ -13,8 +13,6 @@ Post-History: 18-Dec-2019, 13-Jul-2020 .. canonical-typing-spec:: :ref:`typing:paramspec` -:) - Abstract -------- From a27759a2ba24ad3d4899418ab272f20a26b03338 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Fri, 12 Jan 2024 08:46:28 +0200 Subject: [PATCH 6/6] Update link --- .../pep_processor/parsing/pep_banner_directive.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py index dfc87c4559c..00e6af504e5 100644 --- a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py +++ b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py @@ -119,7 +119,7 @@ class CanonicalTypingSpecBanner(PEPBanner): ) admonition_post_text = ( "See the `typing specification update process " - "`__ " + "`__ " "for how to propose changes." ) admonition_class = nodes.attention