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

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

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 <jeremy@alum.mit.edu>
 Status: Withdrawn
 Type: Process
-Content-Type: text/x-rst
 Created: 25-Sep-2000
 Post-History:
 
-
+.. withdrawn::
-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
-This PEP contained guidelines for handling bug reports in the Python
+   <https://devguide.python.org/triage/triaging/index.html>`_.
-bug tracker.  It has been replaced by the Developer's Guide
+   Guidelines for people submitting Python bugs are `in the Python docs
-description of issue triaging at
+   <http://docs.python.org/bugs.html>`__.
-
-::
-
-    https://docs.python.org/devguide/triaging.html
-
-Guidelines for people submitting Python bugs are at
-
-::
-
-    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 <barry@python.org>
 Status: Withdrawn
 Type: Process
-Content-Type: text/x-rst
 Created: 14-Aug-2001
 Post-History:
 Resolution: https://mail.python.org/archives/list/python-dev@python.org/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/python-dev@python.org/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 <jeremy@alum.mit.edu>
 Status: Withdrawn
 Type: Process
-Content-Type: text/x-rst
 Created: 12-Sep-2000
 Post-History:
 
-
+.. withdrawn::
-.. note:: This PEP has been `withdrawn as obsolete`_.
+   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 bug tracker`: https://github.com/python/cpython/issues
-.. _`python-ideas`: https://mail.python.org/mailman/listinfo/python-ideas
+.. _`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 <phd@phdru.name>
 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
+   The content was moved to `Python Wiki`_. Make further updates in the
-with Python development. It is no longer updated.
+   wiki.
 
-The content was moved to `Python Wiki`_. Make further updates in the
+   .. _`Python Wiki`: https://wiki.python.org/moin/Git
-wiki.
-
-.. _`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 <thomas@python.org>
 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 <amk@amk.ca>
 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 <barrett@stsci.edu>, Travis Oliphant <oliphant@ee.byu.edu>
 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 <davida@activestate.com>
 Status: Rejected
 Type: Standards Track
-Content-Type: text/x-rst
 Created: 15-Jul-2000
 Python-Version: 2.1
 Post-History:
 
-
+.. rejected::
-
-..
-  Local Variables:
-  mode: indented-text
-  indent-tabs-mode: nil
-  End:

peps/pep-0211.rst

@@ -3,14 +3,12 @@ Title: Adding A New Outer Product Operator
 Author: Greg Wilson <gvwilson@ddj.com>
 Status: Rejected
 Type: Standards Track
-Content-Type: text/x-rst
 Created: 15-Jul-2000
 Python-Version: 2.1
 Post-History:
 
 
-.. note::
+.. rejected::
-
    The approach in the later :pep:`465` was eventually accepted
    in lieu of this PEP. The :pep:`Rejected Ideas
    <465#rejected-alternatives-to-adding-a-new-operator>`

peps/pep-0215.rst

@@ -3,12 +3,12 @@ Title: String Interpolation
 Author: Ka-Ping Yee <ping@zesty.ca>
 Status: Superseded
 Type: Standards Track
-Content-Type: text/x-rst
 Created: 24-Jul-2000
 Python-Version: 2.1
 Post-History:
 Superseded-By: 292
 
+.. superseded:: 292
 
 Abstract
 ========

peps/pep-0216.rst

@@ -1,19 +1,15 @@
 PEP: 216
 Title: Docstring Format
 Author: Moshe Zadka <moshez@zadka.site.co.il>
-Status: Rejected
+Status: Withdrawn
 Type: Informational
-Content-Type: text/x-rst
 Created: 31-Jul-2000
 Post-History:
 Superseded-By: 287
 
 
-Notice
+.. withdrawn::
-======
+   This PEP is withdrawn by the author.  It has been superseded by :pep:`287`.
-
-This PEP is rejected by the author.  It has been superseded by PEP
-287.
 
 
 Abstract

peps/pep-0220.rst

@@ -3,10 +3,10 @@ Title: Coroutines, Generators, Continuations
 Author: Gordon McMillan <gmcm@hypernet.com>
 Status: Rejected
 Type: Informational
-Content-Type: text/x-rst
 Created: 14-Aug-2000
 Post-History:
 
+.. rejected::
 
 Abstract
 ========

peps/pep-0224.rst

@@ -3,11 +3,13 @@ Title: Attribute Docstrings
 Author: Marc-André Lemburg <mal@lemburg.com>
 Status: Rejected
 Type: Standards Track
-Content-Type: text/x-rst
 Created: 23-Aug-2000
 Python-Version: 2.1
 Post-History:
 
+.. rejected::
+   This PEP has been rejected.
+   See :ref:`224-rejection` for more information.
 
 Introduction
 ============
@@ -173,6 +175,7 @@ docstring attribute and apply the above logic to it.
 Besides generating a docstring for an otherwise undocumented
 attribute there is no breakage.
 
+.. _224-rejection:
 
 Comments from our BDFL
 ======================

peps/pep-0225.rst

@@ -4,14 +4,12 @@ Author: Huaiyu Zhu <hzhu@users.sourceforge.net>,
         Gregory Lielens <gregory.lielens@fft.be>
 Status: Rejected
 Type: Standards Track
-Content-Type: text/x-rst
 Created: 19-Sep-2000
 Python-Version: 2.1
 Post-History:
 
 
-.. note::
+.. rejected::
-
    The approach in the later :pep:`465` was eventually accepted
    in lieu of this PEP. The :pep:`Rejected Ideas
    <465#rejected-alternatives-to-adding-a-new-operator>`

peps/pep-0239.rst

@@ -1,15 +1,24 @@
 PEP: 239
 Title: Adding a Rational Type to Python
-Version: $Revision$
-Last-Modified: $Date$
 Author: Christopher A. Craig <python-pep@ccraig.org>, Moshe Zadka <moshez@zadka.site.co.il>
 Status: Rejected
 Type: Standards Track
-Content-Type: text/x-rst
 Created: 11-Mar-2001
 Python-Version: 2.2
 Post-History: 16-Mar-2001
 
+.. rejected::
+   This PEP is rejected.  The needs outlined in the rationale section
+   have been addressed to some extent by the acceptance of :pep:`327`
+   for decimal arithmetic.  Guido also noted, "Rational arithmetic
+   was the default 'exact' arithmetic in ABC and it did not work out as
+   expected".  See the python-dev discussion on 17 June 2005 [1]_.
+
+   *Postscript:* With the acceptance of :pep:`3141`, "A Type Hierarchy
+   for Numbers", a 'Rational' numeric abstract base class was added
+   with a concrete implementation in the 'fractions' module.
+
+
 
 Abstract
 ========
@@ -21,20 +30,6 @@ support such a type.  This PEP suggests no literals for rational
 numbers; that is left for :pep:`another PEP <240>`.
 
 
-BDFL Pronouncement
-==================
-
-This PEP is rejected.  The needs outlined in the rationale section
-have been addressed to some extent by the acceptance of :pep:`327`
-for decimal arithmetic.  Guido also noted, "Rational arithmetic
-was the default 'exact' arithmetic in ABC and it did not work out as
-expected".  See the python-dev discussion on 17 June 2005 [1]_.
-
-*Postscript:* With the acceptance of :pep:`3141`, "A Type Hierarchy
-for Numbers", a 'Rational' numeric abstract base class was added
-with a concrete implementation in the 'fractions' module.
-
-
 Rationale
 =========
 

peps/pep-0241.rst

@@ -5,11 +5,11 @@ Discussions-To: distutils-sig@python.org
 Status: Superseded
 Type: Standards Track
 Topic: Packaging
-Content-Type: text/x-rst
 Created: 12-Mar-2001
 Post-History: `19-Mar-2001 <https://mail.python.org/archives/list/distutils-sig@python.org/thread/46XPDHQHI3XAAJHEZAMAMKZYAI6K7NB6/>`__
 Superseded-By: 314
 
+.. superseded:: 314
 
 Introduction
 ============
@@ -256,11 +256,3 @@ Copyright
 =========
 
 This document has been placed in the public domain.
-
-
-
-..
-  Local Variables:
-  mode: indented-text
-  indent-tabs-mode: nil
-  End:

peps/pep-0242.rst

@@ -1,13 +1,22 @@
 PEP: 242
 Title: Numeric Kinds
 Author: Paul F. Dubois <paul@pfdubois.com>
-Status: Rejected
+Status: Withdrawn
 Type: Standards Track
-Content-Type: text/x-rst
 Created: 17-Mar-2001
 Python-Version: 2.2
 Post-History: 17-Apr-2001
 
+.. withdrawn::
+   This PEP has been closed by the author.  The kinds module will not
+   be added to the standard library.
+
+   There was no opposition to the proposal but only mild interest in
+   using it, not enough to justify adding the module to the standard
+   library.  Instead, it will be made available as a separate
+   distribution item at the Numerical Python site.  At the next
+   release of Numerical Python, it will no longer be a part of the
+   Numeric distribution.
 
 Abstract
 ========
@@ -217,20 +226,6 @@ Open Issues
 No open issues have been raised at this time.
 
 
-Rejection
-=========
-
-This PEP has been closed by the author.  The kinds module will not
-be added to the standard library.
-
-There was no opposition to the proposal but only mild interest in
-using it, not enough to justify adding the module to the standard
-library.  Instead, it will be made available as a separate
-distribution item at the Numerical Python site.  At the next
-release of Numerical Python, it will no longer be a part of the
-Numeric distribution.
-
-
 Copyright
 =========
 

peps/pep-0363.rst

@@ -1,14 +1,14 @@
 PEP: 363
 Title: Syntax For Dynamic Attribute Access
-Version: $Revision$
-Last-Modified: $Date$
 Author: Ben North <ben@redfrontdoor.org>
 Status: Rejected
 Type: Standards Track
-Content-Type: text/x-rst
 Created: 29-Jan-2007
 Post-History: 12-Feb-2007
 
+.. rejected::
+   This PEP has been rejected.
+   See :ref:`363-rejection` for more information.
 
 Abstract
 ========
@@ -172,6 +172,8 @@ of c.180 additional lines in the core code, and c.100 additional
 lines of tests.  It is available as sourceforge patch #1657573 [1]_.
 
 
+.. _363-rejection:
+
 Mailing Lists Discussion
 ========================
 
@@ -249,12 +251,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:

peps/pep-0426.rst

@@ -1,7 +1,5 @@
 PEP: 426
 Title: Metadata for Python Software Packages 2.0
-Version: $Revision$
-Last-Modified: $Date$
 Author: Alyssa Coghlan <ncoghlan@gmail.com>,
         Daniel Holth <dholth@gmail.com>,
         Donald Stufft <donald@stufft.io>
@@ -10,7 +8,6 @@ Discussions-To: distutils-sig@python.org
 Status: Withdrawn
 Type: Informational
 Topic: Packaging
-Content-Type: text/x-rst
 Requires: 440, 508, 518
 Created: 30-Aug-2012
 Post-History: 14-Nov-2012, 05-Feb-2013, 07-Feb-2013, 09-Feb-2013,
@@ -18,19 +15,16 @@ Post-History: 14-Nov-2012, 05-Feb-2013, 07-Feb-2013, 09-Feb-2013,
               21-Dec-2013
 Replaces: 345
 
-
+.. withdrawn::
-PEP Withdrawal
+   The ground-up metadata redesign proposed in this PEP has been withdrawn in
-==============
+   favour of the more modest proposal in :pep:`566`, which retains the basic
-
+   Key:Value format of previous metadata versions, but also defines a standardised
-The ground-up metadata redesign proposed in this PEP has been withdrawn in
+   mechanism for translating that format to nested JSON-compatible data structures.
-favour of the more modest proposal in :pep:`566`, which retains the basic
+   
-Key:Value format of previous metadata versions, but also defines a standardised
+   Some of the ideas in this PEP (or the related :pep:`459`) may still be considered
-mechanism for translating that format to nested JSON-compatible data structures.
+   as part of later proposals, but they will be handled in a more incremental
-
+   fashion, rather than as a single large proposed change with no feasible
-Some of the ideas in this PEP (or the related :pep:`459`) may still be considered
+   migration plan.
-as part of later proposals, but they will be handled in a more incremental
-fashion, rather than as a single large proposed change with no feasible
-migration plan.
 
 
 Abstract