Infra: Add directives to show warning banner for deprecated PEPs (#3682)

Co-authored-by: C.A.M. Gerlach <[email protected]>

Author: hugovk

pep_sphinx_extensions/__init__.py

@@ -75,6 +75,9 @@ def setup(app: Sphinx) -> dict[str, bool]:
         "canonical-pypa-spec", pep_banner_directive.CanonicalPyPASpecBanner)
     app.add_directive(
         "canonical-typing-spec", pep_banner_directive.CanonicalTypingSpecBanner)
+    app.add_directive("rejected", pep_banner_directive.RejectedBanner)
+    app.add_directive("superseded", pep_banner_directive.SupersededBanner)
+    app.add_directive("withdrawn", pep_banner_directive.WithdrawnBanner)
 
     # Register event callbacks
     app.connect("builder-inited", _update_config_for_builder)  # Update configuration values for builder used

pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py

@@ -125,3 +125,34 @@ class CanonicalTypingSpecBanner(PEPBanner):
     admonition_class = nodes.attention
 
     css_classes = ["canonical-typing-spec", "sticky-banner"]
+
+
+class DeprecatedBanner(PEPBanner):
+    """Generic admonition for deprecated PEPs."""
+
+    admonition_class = nodes.warning
+    admonition_pre_template = "{link_content}"
+    admonition_pre_text = "This PEP has been deprecated."
+    css_classes = ["sticky-banner", "deprecated"]
+
+
+class RejectedBanner(DeprecatedBanner):
+    """Insert an admonition for rejected PEPs."""
+
+    admonition_pre_text = "This PEP has been rejected."
+    css_classes = ["sticky-banner", "deprecated", "rejected"]
+
+
+class SupersededBanner(PEPBanner):
+    """Insert an admonition for superseded PEPs."""
+
+    admonition_pre_template = "This PEP has been superseded by :pep:`{link_content}`."
+    admonition_pre_text = "This PEP has been superseded."
+    css_classes = ["sticky-banner", "deprecated", "superseded"]
+
+
+class WithdrawnBanner(PEPBanner):
+    """Insert an admonition for withdrawn PEPs."""
+
+    admonition_pre_text = "This PEP has been withdrawn."
+    css_classes = ["sticky-banner", "deprecated", "withdrawn"]

peps/pep-0003.rst

@@ -3,27 +3,16 @@ Title: Guidelines for Handling Bug Reports
 Author: Jeremy Hylton <[email protected]>
 Status: Withdrawn
 Type: Process
-Content-Type: text/x-rst
 Created: 25-Sep-2000
 Post-History:
 
-
-Introduction
-============
-
-This PEP contained guidelines for handling bug reports in the Python
-bug tracker.  It has been replaced by the Developer's Guide
-description of issue triaging at
-
-::
-
-    https://docs.python.org/devguide/triaging.html
-
-Guidelines for people submitting Python bugs are at
-
-::
-
-    http://docs.python.org/bugs.html
+.. withdrawn::
+   This PEP contained guidelines for handling bug reports in the Python
+   bug tracker.  It has been replaced by the
+   `Developer's Guide description of issue triaging
+   <https://devguide.python.org/triage/triaging/index.html>`_.
+   Guidelines for people submitting Python bugs are `in the Python docs
+   <http://docs.python.org/bugs.html>`__.
 
 Original Guidelines
 ===================

peps/pep-0009.rst

@@ -1,25 +1,20 @@
 PEP: 9
 Title: Sample Plaintext PEP Template
-Version: $Revision$
-Last-Modified: $Date$
 Author: Barry Warsaw <[email protected]>
 Status: Withdrawn
 Type: Process
-Content-Type: text/x-rst
 Created: 14-Aug-2001
 Post-History:
 Resolution: https://mail.python.org/archives/list/[email protected]/thread/2YMHVPRDWGQLA5A2FKXE2JMLM2HQEEGW/
 
+.. withdrawn::
+   As of 05-Jan-2016, this PEP is officially deprecated and replaced
+   by :pep:`12`.  All PEPs should now use the reStructuredText format
+   described by :pep:`12`, and plaintext PEPs will no longer be
+   accepted.
 
 ::
 
-  Update
-
-      As of 05-Jan-2016, this PEP is officially deprecated and replaced
-      by PEP 12.  All PEPs should now use the reStructuredText format
-      described by PEP 12, and plaintext PEPs will no longer be
-      accepted.
-
   Abstract
 
       This PEP provides a boilerplate or sample template for creating
@@ -225,14 +220,3 @@ Resolution: https://mail.python.org/archives/list/[email protected]/thread/2
   Copyright
 
       This document has been placed in the public domain.
-
-
-
-..
-   Local Variables:
-   mode: indented-text
-   indent-tabs-mode: nil
-   sentence-end-double-space: t
-   fill-column: 70
-   coding: utf-8
-   End:

peps/pep-0042.rst

@@ -1,18 +1,15 @@
 PEP: 42
 Title: Feature Requests
-Version: $Revision$
-Last-Modified: $Date$
 Author: Jeremy Hylton <[email protected]>
 Status: Withdrawn
 Type: Process
-Content-Type: text/x-rst
 Created: 12-Sep-2000
 Post-History:
 
-
-.. note:: This PEP has been `withdrawn as obsolete`_.
+.. withdrawn::
+   This PEP has been `withdrawn as obsolete`_.
    All new feature requests should  either go to the `Python bug tracker`_
-   for very simple requests or the `python-ideas`_ mailing list for
+   for very simple requests or the `Ideas Discourse category`_ for
    everything else.  The rest of this document is retained for historical
    purposes only.
 
@@ -332,13 +329,6 @@ Building and Installing
 
   http://bugs.python.org/issue588756
 
-.. _`Python bug tracker`: https://bugs.python.org
-.. _`python-ideas`: https://mail.python.org/mailman/listinfo/python-ideas
+.. _`Python bug tracker`: https://github.com/python/cpython/issues
+.. _`Ideas Discourse category`: https://discuss.python.org/c/ideas/6
 .. _`withdrawn as obsolete`: https://github.com/python/peps/pull/108#issuecomment-249603204
-
-
-..
-   Local Variables:
-   mode: indented-text
-   indent-tabs-mode: nil
-   End:

peps/pep-0103.rst

@@ -1,24 +1,19 @@
 PEP: 103
 Title: Collecting information about git
-Version: $Revision$
-Last-Modified: $Date$
 Author: Oleg Broytman <[email protected]>
 Status: Withdrawn
 Type: Informational
-Content-Type: text/x-rst
 Created: 01-Jun-2015
 Post-History: 12-Sep-2015
 
-Withdrawal
-==========
+.. withdrawn::
+   This PEP was withdrawn as it's too generic and doesn't really deals
+   with Python development. It is no longer updated.
 
-This PEP was withdrawn as it's too generic and doesn't really deals
-with Python development. It is no longer updated.
+   The content was moved to `Python Wiki`_. Make further updates in the
+   wiki.
 
-The content was moved to `Python Wiki`_. Make further updates in the
-wiki.
-
-.. _`Python Wiki`: https://wiki.python.org/moin/Git
+   .. _`Python Wiki`: https://wiki.python.org/moin/Git
 
 Abstract
 ========
@@ -1076,15 +1071,3 @@ Copyright
 =========
 
 This document has been placed in the public domain.
-
-
-
-..
-   Local Variables:
-   mode: indented-text
-   indent-tabs-mode: nil
-   sentence-end-double-space: t
-   fill-column: 70
-   coding: utf-8
-   End:
-   vim: set fenc=us-ascii tw=70 :

peps/pep-0204.rst

@@ -3,11 +3,21 @@ Title: Range Literals
 Author: Thomas Wouters <[email protected]>
 Status: Rejected
 Type: Standards Track
-Content-Type: text/x-rst
 Created: 14-Jul-2000
 Python-Version: 2.0
 Post-History:
 
+.. rejected::
+   After careful consideration, and a period of meditation, this
+   proposal has been rejected. The open issues, as well as some
+   confusion between ranges and slice syntax, raised enough questions
+   for Guido not to accept it for Python 2.0, and later to reject the
+   proposal altogether. The new syntax and its intentions were deemed
+   not obvious enough.
+
+   [ TBD: Guido, amend/confirm this, please. Preferably both; this
+   is a PEP, it should contain *all* the reasons for rejection
+   and/or reconsideration, for future reference. ]
 
 Introduction
 ============
@@ -270,21 +280,6 @@ Open issues
   made private functions?
 
 
-Rejection
-=========
-
-After careful consideration, and a period of meditation, this
-proposal has been rejected. The open issues, as well as some
-confusion between ranges and slice syntax, raised enough questions
-for Guido not to accept it for Python 2.0, and later to reject the
-proposal altogether. The new syntax and its intentions were deemed
-not obvious enough.
-
-[ TBD: Guido, amend/confirm this, please. Preferably both; this
-is a PEP, it should contain *all* the reasons for rejection
-and/or reconsideration, for future reference. ]
-
-
 Copyright
 =========
 

peps/pep-0206.rst

@@ -1,14 +1,12 @@
 PEP: 206
 Title: Python Advanced Library
-Version: $Revision$
-Last-Modified: $Date$
 Author: A.M. Kuchling <[email protected]>
 Status: Withdrawn
 Type: Informational
-Content-Type: text/x-rst
 Created: 14-Jul-2000
 Post-History:
 
+.. withdrawn::
 
 Introduction
 ============
@@ -119,10 +117,3 @@ Acknowledgements
 
 The PEP is based on an earlier draft PEP by Moshe Zadka, titled
 "2.0 Batteries Included."
-
-
-..
-  Local Variables:
-  mode: indented-text
-  indent-tabs-mode: nil
-  End:

peps/pep-0209.rst

@@ -3,11 +3,11 @@ Title: Multi-dimensional Arrays
 Author: Paul Barrett <[email protected]>, Travis Oliphant <[email protected]>
 Status: Withdrawn
 Type: Standards Track
-Content-Type: text/x-rst
 Created: 03-Jan-2001
 Python-Version: 2.2
 Post-History:
 
+.. withdrawn::
 
 Abstract
 ========

peps/pep-0210.rst

@@ -3,15 +3,8 @@ Title: Decoupling the Interpreter Loop
 Author: David Ascher <[email protected]>
 Status: Rejected
 Type: Standards Track
-Content-Type: text/x-rst
 Created: 15-Jul-2000
 Python-Version: 2.1
 Post-History:
 
-
-
-..
-  Local Variables:
-  mode: indented-text
-  indent-tabs-mode: nil
-  End:
+.. rejected::