Use an option instead of argument in banner directives

When a reST directive has both `has_content` set to `True`, optional
arguments and `final_argument_whitespace` set to True, the presence of a
newline at the start of the directive is significant in communicating
whether specific markup is treated as the argument or content.

    .. banner-1:: This is an argument
       This is still the argument.

       This is content.

    .. banner-2::
       This is still the argument.

       This is content.

    .. banner-3::

       This is content.

       This is more content.

In the above example, `banner-2` and `banner-3` are very similar
and only different in the presence of a newline. This is a
subtle failure mode where written content can end up being silently ignored by
the reST directive due to how arguments vs contents are parsed.

Instead of attempting to accommodate for this failure mode by adding
additional complexity to the directive being used, the approach taken
here moves away from trying to mix multiline arguments and content in a
single directive by using explicit options instead. This requires more
verbosity but also eliminates this failure mode entirely.

    .. banner-1::
       :option: This is the option.
                This is still the option.

    .. banner-2::
       This is content.

       This is still content.

    .. banner-3::

       This is content.

       This is still content.

With this change, presence of a newline at the start of the directive is
not determining if specific markup is treated as the argument or
content. This is instead communicated by the presence of the option
syntax which is more explicit and presents proper errors when the syntax
is incorrect.

Author: pradyunsg

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 @@ class PEPBanner(rst.Directive):
 
     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,11 +27,9 @@ class PEPBanner(rst.Directive):
     css_classes = []
 
     def run(self) -> list[nodes.admonition]:
-
-        if self.arguments:
-            link_content = self.arguments[0]
+        if 'related' in self.options:
             pre_text = self.admonition_pre_template.format(
-                link_content=link_content)
+                link_content=self.options['related'])
         else:
             pre_text = self.admonition_pre_text
 

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/[email protected]/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/[email protected]/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
 ========