Infra: Use an option instead of argument in banner directives

pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py

@@ -4,6 +4,7 @@
 
 from docutils import nodes
 from docutils.parsers import rst
+from docutils.parsers.rst import directives
 
 PYPA_SPEC_BASE_URL = "https://packaging.python.org/en/latest/specifications/"
 TYPING_SPEC_BASE_URL = "https://typing.readthedocs.io/en/latest/spec/"
@@ -14,9 +15,9 @@
 
     has_content = True
     required_arguments = 0
-    optional_arguments = 1
-    final_argument_whitespace = True
-    option_spec = {}
+    option_spec = {
+        'related': directives.unchanged,
+    }
 
     admonition_pre_template = ""
     admonition_pre_text = ""
@@ -26,9 +27,7 @@
     css_classes = []
 
     def run(self) -> list[nodes.admonition]:
-
-        if self.arguments:
-            link_content = self.arguments[0]
+        if link_content := self.options.get('related', ''):
             pre_text = self.admonition_pre_template.format(
                 link_content=link_content)
         else:

peps/pep-0012.rst

@@ -677,34 +677,40 @@ For example,
 to create a banner pointing to the :mod:`python:sqlite3` docs,
 you would write the following::
 
-    .. canonical-doc:: :mod:`python:sqlite3`
+    .. canonical-doc::
+       :related: :mod:`python:sqlite3`
 
 which would generate the banner:
 
-    .. canonical-doc:: :mod:`python:sqlite3`
+    .. canonical-doc::
+       :related: :mod:`python:sqlite3`
 
 Or for a PyPA spec,
 such as the :ref:`packaging:core-metadata`,
 you would use::
 
-    .. canonical-pypa-spec:: :ref:`packaging:core-metadata`
+    .. canonical-pypa-spec::
+      :related: :ref:`packaging:core-metadata`
 
 which renders as:
 
-    .. canonical-pypa-spec:: :ref:`packaging:core-metadata`
+    .. canonical-pypa-spec::
+       :related: :ref:`packaging:core-metadata`
 
 The argument accepts arbitrary reST,
 so you can include multiple linked docs/specs and name them whatever you like,
 and you can also include directive content that will be inserted into the text.
 The following advanced example::
 
-    .. canonical-doc:: the :ref:`python:sqlite3-connection-objects` and :exc:`python:~sqlite3.DataError` docs
+    .. canonical-doc::
+       :related: the :ref:`python:sqlite3-connection-objects` and :exc:`python:~sqlite3.DataError` docs
 
         Also, see the :ref:`Data Persistence docs <persistence>` for other examples.
 
 would render as:
 
-    .. canonical-doc:: the :ref:`python:sqlite3-connection-objects` and :exc:`python:sqlite3.DataError` docs
+    .. canonical-doc::
+       :related: the :ref:`python:sqlite3-connection-objects` and :exc:`python:sqlite3.DataError` docs
 
         Also, see the :ref:`Data Persistence docs <persistence>` for other examples.
 

peps/pep-0215.rst

@@ -8,7 +8,8 @@ Python-Version: 2.1
 Post-History:
 Superseded-By: 292
 
-.. superseded:: 292
+.. superseded::
+   :related: 292
 
 Abstract
 ========

peps/pep-0241.rst

@@ -9,7 +9,8 @@ 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
+.. superseded::
+   :related: 314
 
 Introduction
 ============

peps/pep-0384.rst

@@ -8,8 +8,9 @@ Created: 17-May-2009
 Python-Version: 3.2
 Post-History:
 
-.. canonical-doc:: :ref:`python:stable` (user docs) and
-                   :ref:`devguide:c-api` (development docs)
+.. canonical-doc::
+   :related: :ref:`python:stable` (user docs) and
+             :ref:`devguide:c-api` (development docs)
 
 Abstract
 ========

peps/pep-0425.rst

@@ -14,7 +14,8 @@ Post-History: 08-Aug-2012, 18-Oct-2012, 15-Feb-2013
 Resolution: https://mail.python.org/pipermail/python-dev/2013-February/124116.html
 
 
-.. canonical-pypa-spec:: :ref:`packaging:platform-compatibility-tags`
+.. canonical-pypa-spec::
+   :related: :ref:`packaging:platform-compatibility-tags`
 
 
 Abstract

peps/pep-0427.rst

@@ -14,7 +14,8 @@ Post-History: 18-Oct-2012, 15-Feb-2013
 Resolution: https://mail.python.org/pipermail/python-dev/2013-February/124103.html
 
 
-.. canonical-pypa-spec:: :ref:`packaging:binary-distribution-format`
+.. canonical-pypa-spec::
+   :related: :ref:`packaging:binary-distribution-format`
 
 
 Abstract

peps/pep-0440.rst

@@ -15,7 +15,8 @@ Post-History: 30-Mar-2013, 27-May-2013, 20-Jun-2013,
 Replaces: 386
 Resolution: https://mail.python.org/pipermail/distutils-sig/2014-August/024673.html
 
-.. canonical-pypa-spec:: :ref:`version-specifiers`
+.. canonical-pypa-spec::
+   :related: :ref:`version-specifiers`
 
 
 Abstract

peps/pep-0544.rst

@@ -10,7 +10,8 @@ Created: 05-Mar-2017
 Python-Version: 3.8
 Resolution: https://mail.python.org/archives/list/typing-sig@python.org/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
 
-.. canonical-typing-spec:: :ref:`typing:protocols`
+.. canonical-typing-spec::
+   :related: :ref:`typing:protocols`
 
 
 Abstract

peps/pep-0560.rst

@@ -9,8 +9,9 @@ Python-Version: 3.7
 Post-History: 09-Sep-2017, 14-Nov-2017
 Resolution: https://mail.python.org/pipermail/python-dev/2017-December/151038.html
 
-.. canonical-doc:: :external+python:meth:`object.__class_getitem__` and
-                   :external+python:meth:`object.__mro_entries__`
+.. canonical-doc::
+   :related: :external+python:meth:`object.__class_getitem__` and
+             :external+python:meth:`object.__mro_entries__`
 
 Abstract
 ========

peps/pep-0566.rst

@@ -14,7 +14,8 @@ Replaces: 345
 Resolution: https://mail.python.org/pipermail/distutils-sig/2018-February/032014.html
 
 
-.. canonical-pypa-spec:: :ref:`packaging:core-metadata`
+.. canonical-pypa-spec::
+   :related: :ref:`packaging:core-metadata`
 
 
 Abstract

peps/pep-0586.rst

@@ -11,7 +11,8 @@ Python-Version: 3.8
 Post-History: 14-Mar-2019
 Resolution: https://mail.python.org/archives/list/typing-sig@python.org/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
 
-.. canonical-typing-spec:: :ref:`typing:literal-types`
+.. canonical-typing-spec::
+   :related: :ref:`typing:literal-types`
 
 Abstract
 ========

peps/pep-0589.rst

@@ -12,7 +12,8 @@ Python-Version: 3.8
 Post-History:
 Resolution: https://mail.python.org/archives/list/typing-sig@python.org/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
 
-.. canonical-typing-spec:: :ref:`typing:typeddict`
+.. canonical-typing-spec::
+   :related: :ref:`typing:typeddict`
 
 Abstract
 ========

peps/pep-0591.rst

@@ -11,7 +11,8 @@ Python-Version: 3.8
 Post-History:
 Resolution: https://mail.python.org/archives/list/typing-sig@python.org/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
 
-.. canonical-typing-spec:: :ref:`typing:at-final` and :ref:`typing:uppercase-final`
+.. canonical-typing-spec::
+   :related: :ref:`typing:at-final` and :ref:`typing:uppercase-final`
 
 Abstract
 ========

peps/pep-0593.rst

@@ -10,7 +10,8 @@ Created: 26-Apr-2019
 Python-Version: 3.9
 Post-History: 20-May-2019
 
-.. canonical-typing-spec:: :ref:`annotated`
+.. canonical-typing-spec::
+   :related: :ref:`annotated`
 
 Abstract
 --------

peps/pep-0604.rst

@@ -11,7 +11,8 @@ Created: 28-Aug-2019
 Python-Version: 3.10
 Post-History: 28-Aug-2019, 05-Aug-2020
 
-.. canonical-doc:: :ref:`python:types-union`
+.. canonical-doc::
+   :related: :ref:`python:types-union`
 
 Abstract
 ========

peps/pep-0610.rst

@@ -13,7 +13,8 @@ Post-History:
 Resolution: https://discuss.python.org/t/1535/56
 
 
-.. canonical-pypa-spec:: :ref:`packaging:direct-url`
+.. canonical-pypa-spec::
+   :related: :ref:`packaging:direct-url`
 
 
 Abstract

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-typing-spec:: :ref:`typing:paramspec`
+.. canonical-typing-spec::
+   :related: :ref:`typing:paramspec`
 
 Abstract
 --------

peps/pep-0613.rst

@@ -10,7 +10,8 @@ Created: 21-Jan-2020
 Python-Version: 3.10
 Post-History: 21-Jan-2020
 
-.. canonical-typing-spec:: :ref:`typing:type-aliases`
+.. canonical-typing-spec::
+   :related: :ref:`typing:type-aliases`
 
 Abstract
 ========

peps/pep-0617.rst

@@ -10,7 +10,8 @@ Created: 24-Mar-2020
 Python-Version: 3.9
 Post-History: 02-Apr-2020
 
-.. canonical-doc:: :ref:`python:full-grammar-specification`
+.. canonical-doc::
+   :related: :ref:`python:full-grammar-specification`
 
 .. highlight:: PEG
 

peps/pep-0621.rst

@@ -20,7 +20,8 @@ Post-History: 22-Jun-2020,
 Resolution: https://discuss.python.org/t/pep-621-round-3/5472/109
 
 
-.. canonical-pypa-spec:: :ref:`packaging:pyproject-toml-spec`
+.. canonical-pypa-spec::
+   :related: :ref:`packaging:pyproject-toml-spec`
 
 
 Abstract

peps/pep-0627.rst

@@ -11,7 +11,8 @@ Created: 15-Jul-2020
 Resolution: https://discuss.python.org/t/pep-627/4126/42
 
 
-.. canonical-pypa-spec:: :ref:`packaging:recording-installed-packages`
+.. canonical-pypa-spec::
+   :related: :ref:`packaging:recording-installed-packages`
 
 
 Abstract

peps/pep-0630.rst

@@ -11,7 +11,8 @@ Post-History: 16-Jul-2020
 
 .. highlight:: c
 
-.. canonical-doc:: `Isolating Extension Modules HOWTO <https://docs.python.org/3.11/howto/isolating-extensions.html>`_
+.. canonical-doc::
+   :related: `Isolating Extension Modules HOWTO <https://docs.python.org/3.11/howto/isolating-extensions.html>`_
 
 Abstract
 ========

peps/pep-0634.rst

@@ -12,7 +12,8 @@ Post-History: 22-Oct-2020, 08-Feb-2021
 Replaces: 622
 Resolution: https://mail.python.org/archives/list/python-committers@python.org/message/SQC2FTLFV5A7DV7RCEAR2I2IKJKGK7W3
 
-.. canonical-doc:: :external+python:ref:`match`
+.. canonical-doc::
+   :related: :external+python:ref:`match`
 
 Abstract
 ========

peps/pep-0643.rst

@@ -12,7 +12,8 @@ Post-History: 24-Oct-2020, 01-Nov-2020, 02-Nov-2020, 14-Nov-2020
 Resolution: https://discuss.python.org/t/pep-643-metadata-for-package-source-distributions/5577/53
 
 
-.. canonical-pypa-spec:: :ref:`packaging:core-metadata`
+.. canonical-pypa-spec::
+   :related: :ref:`packaging:core-metadata`
 
 
 Abstract

peps/pep-0647.rst

@@ -11,7 +11,8 @@ Python-Version: 3.10
 Post-History: 28-Dec-2020, 09-Apr-2021
 Resolution: https://mail.python.org/archives/list/python-dev@python.org/thread/2ME6F6YUVKHOQYKSHTVQQU5WD4CVAZU4/
 
-.. canonical-typing-spec:: :ref:`typing:typeguard`
+.. canonical-typing-spec::
+   :related: :ref:`typing:typeguard`
 
 Abstract
 ========

peps/pep-0652.rst

@@ -10,8 +10,9 @@ Python-Version: 3.10
 Resolution: https://mail.python.org/archives/list/python-dev@python.org/message/IN4XMFLQJ6D6V67EXU27GV3QWSEHHNNH/
 
 
-.. canonical-doc:: :ref:`python:stable` (user docs) and
-                   :ref:`devguide:c-api` (development docs)
+.. canonical-doc::
+   :related: :ref:`python:stable` (user docs) and
+             :ref:`devguide:c-api` (development docs)
 
 Abstract
 ========

peps/pep-0654.rst

@@ -14,7 +14,8 @@ Post-History: `22-Feb-2021 <https://mail.python.org/archives/list/python-dev@pyt
               `03-Oct-2021 <https://mail.python.org/archives/list/python-dev@python.org/thread/4B256YKUPW5P2M44GG5H6FBL3PSV6ODP/>`__,
 Resolution: https://discuss.python.org/t/accepting-pep-654-exception-groups-and-except/10813/1
 
-.. canonical-doc:: :ref:`python:lib-exception-groups` and :ref:`python:except_star`
+.. canonical-doc::
+   :related: :ref:`python:lib-exception-groups` and :ref:`python:except_star`
 
    See :ref:`python:tut-exception-groups` for a user-focused tutorial.
 

peps/pep-0655.rst

@@ -11,7 +11,8 @@ Python-Version: 3.11
 Post-History: 31-Jan-2021, 11-Feb-2021, 20-Feb-2021, 26-Feb-2021, 17-Jan-2022, 28-Jan-2022
 Resolution: https://mail.python.org/archives/list/python-dev@python.org/message/AJEDNVC3FXM5QXNNW5CR4UCT4KI5XVUE/
 
-.. canonical-typing-spec:: :ref:`typing:required-notrequired`
+.. canonical-typing-spec::
+   :related: :ref:`typing:required-notrequired`
 
 Abstract
 ========

peps/pep-0668.rst

@@ -18,7 +18,8 @@ Created: 18-May-2021
 Post-History: 28-May-2021
 Resolution: https://discuss.python.org/t/10302/44
 
-.. canonical-pypa-spec:: :ref:`externally-managed-environments`
+.. canonical-pypa-spec::
+   :related: :ref:`externally-managed-environments`
 
 Abstract
 ========

peps/pep-0669.rst

@@ -10,7 +10,8 @@ Post-History: `07-Dec-2021 <https://mail.python.org/archives/list/python-dev@pyt
               `10-Jan-2022 <https://discuss.python.org/t/pep-669-low-impact-monitoring-for-cpython/13018>`__,
 Resolution: https://discuss.python.org/t/pep-669-low-impact-monitoring-for-cpython/13018/42
 
-.. canonical-doc:: :mod:`python:sys.monitoring`
+.. canonical-doc::
+   :related: :mod:`python:sys.monitoring`
 
 Abstract
 ========

peps/pep-0673.rst

@@ -12,7 +12,8 @@ Python-Version: 3.11
 Post-History: 17-Nov-2021
 Resolution: https://mail.python.org/archives/list/python-dev@python.org/thread/J7BWL5KWOPQQK5KFWKENVLXW6UGSPTGI/
 
-.. canonical-typing-spec:: :ref:`typing:self`
+.. canonical-typing-spec::
+   :related: :ref:`typing:self`
 
 Abstract
 ========

peps/pep-0675.rst

@@ -11,7 +11,8 @@ Python-Version: 3.11
 Post-History: 07-Feb-2022
 Resolution: https://mail.python.org/archives/list/python-dev@python.org/message/XEOOSSPNYPGZ5NXOJFPLXG2BTN7EVRT5/
 
-.. canonical-typing-spec:: :ref:`typing:literalstring`
+.. canonical-typing-spec::
+   :related: :ref:`typing:literalstring`
 
 Abstract
 ========