Use an option instead of argument in banner directives

When a reST directive has `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 accommodating for this behaviour by adding additional complexity to the directive being used, this change stops 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.
python · pradyunsg · Apr 28, 2024 · May 6, 2024 · Apr 28, 2024 · a8a4bfb53f195710d6c9b3fe715d21d3b5fc9bdf
commit a8a4bfb53f195710d6c9b3fe715d21d3b5fc9bdf
@@ -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
 

@@ -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.
 

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

@@ -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
 ============

@@ -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
 ========

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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
 ========

@@ -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

@@ -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
 ========

@@ -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
 ========

@@ -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
 ========

@@ -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
 --------

@@ -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
 ========

@@ -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

@@ -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
 --------

@@ -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
 ========

@@ -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
 

@@ -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:pypro
BD94
ject-toml-spec`
 
 
 Abstract

@@ -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

@@ -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
 ========

@@ -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
 ========

@@ -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

@@ -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
 ========

@@ -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
 ========

@@ -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.
 

diff --git a/10000 b/10000
@@ -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
 ========

@@ -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
 ========

@@ -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
 ========

@@ -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
 ========

@@ -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
 ========