diff --git a/.github/PULL_REQUEST_TEMPLATE/Mark a PEP Final.md b/.github/PULL_REQUEST_TEMPLATE/Mark a PEP Final.md index 25463c773..cc667804f 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 8538b838a..f3aaa8ea8 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 6b247bcc5..00e6af504 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 import nodes 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 09b9b3ed3..d8e851a50 100644 --- a/peps/conf.py +++ b/peps/conf.py @@ -52,6 +52,7 @@ nitpicky = True 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 073a74dc0..8f684fdf0 100644 --- a/peps/pep-0012.rst +++ b/peps/pep-0012.rst @@ -653,9 +653,11 @@ 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 -or an appropriate subclass -(currently ``canonical-pypa-spec`` for packaging standards). +To indicate this, use the ``canonical-doc`` directive +or an appropriate subclass: + +* ``canonical-pypa-spec`` for packaging standards +* ``canonical-typing-spec`` for typing standards Furthermore, you can use `Intersphinx references diff --git a/peps/pep-0612.rst b/peps/pep-0612.rst index a5c51d3a0..78aac53b3 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-typing-spec:: :ref:`typing:paramspec` Abstract --------