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 · Apr 28, 2024 · a8a4bfb · a8a4bfb
1 parent 72595af
commit a8a4bfb
Show file tree

Hide file tree

Showing 45 changed files with 112 additions and 64 deletions.
diff --git a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py b/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
 

diff --git a/peps/pep-0012.rst b/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.
 

diff --git a/peps/pep-0215.rst b/peps/pep-0215.rst
@@ -8,7 +8,8 @@ Python-Version: 2.1
 Post-History:
 Superseded-By: 292
 
-.. superseded:: 292
+.. superseded::
+   :related: 292
 
 Abstract
 ========

diff --git a/peps/pep-0241.rst b/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
 ============

diff --git a/peps/pep-0384.rst b/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
 ========

diff --git a/peps/pep-0425.rst b/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

diff --git a/peps/pep-0427.rst b/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

diff --git a/peps/pep-0440.rst b/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

diff --git a/peps/pep-0544.rst b/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

diff --git a/peps/pep-0560.rst b/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
 ========

diff --git a/peps/pep-0566.rst b/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

diff --git a/peps/pep-0586.rst b/peps/pep-0586.rst
@@ -11,7 +11,8 @@ Python-Version: 3.8
 Post-History: 14-Mar-2019
 Resolution: https://mail.python.org/archives/list/[email protected]/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
 
-.. canonical-typing-spec:: :ref:`typing:literal-types`
+.. canonical-typing-spec::
+   :related: :ref:`typing:literal-types`
 
 Abstract
 ========

diff --git a/peps/pep-0589.rst b/peps/pep-0589.rst
@@ -12,7 +12,8 @@ Python-Version: 3.8
 Post-History:
 Resolution: https://mail.python.org/archives/list/[email protected]/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
 
-.. canonical-typing-spec:: :ref:`typing:typeddict`
+.. canonical-typing-spec::
+   :related: :ref:`typing:typeddict`
 
 Abstract
 ========

diff --git a/peps/pep-0591.rst b/peps/pep-0591.rst
@@ -11,7 +11,8 @@ Python-Version: 3.8
 Post-History:
 Resolution: https://mail.python.org/archives/list/[email protected]/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
 ========

diff --git a/peps/pep-0593.rst b/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
 --------

diff --git a/peps/pep-0604.rst b/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
 ========

diff --git a/peps/pep-0610.rst b/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

diff --git a/peps/pep-0612.rst b/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
 --------

diff --git a/peps/pep-0613.rst b/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
 ========

diff --git a/peps/pep-0617.rst b/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
 

diff --git a/peps/pep-0621.rst b/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

diff --git a/peps/pep-0627.rst b/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

diff --git a/peps/pep-0630.rst b/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
 ========

diff --git a/peps/pep-0634.rst b/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/[email protected]/message/SQC2FTLFV5A7DV7RCEAR2I2IKJKGK7W3
 
-.. canonical-doc:: :external+python:ref:`match`
+.. canonical-doc::
+   :related: :external+python:ref:`match`
 
 Abstract
 ========

diff --git a/peps/pep-0643.rst b/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

diff --git a/peps/pep-0647.rst b/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/[email protected]/thread/2ME6F6YUVKHOQYKSHTVQQU5WD4CVAZU4/
 
-.. canonical-typing-spec:: :ref:`typing:typeguard`
+.. canonical-typing-spec::
+   :related: :ref:`typing:typeguard`
 
 Abstract
 ========

diff --git a/peps/pep-0652.rst b/peps/pep-0652.rst
@@ -10,8 +10,9 @@ Python-Version: 3.10
 Resolution: https://mail.python.org/archives/list/[email protected]/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
 ========

diff --git a/peps/pep-0654.rst b/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/[email protected]/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/peps/pep-0655.rst b/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/[email protected]/message/AJEDNVC3FXM5QXNNW5CR4UCT4KI5XVUE/
 
-.. canonical-typing-spec:: :ref:`typing:required-notrequired`
+.. canonical-typing-spec::
+   :related: :ref:`typing:required-notrequired`
 
 Abstract
 ========

diff --git a/peps/pep-0668.rst b/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
 ========

diff --git a/peps/pep-0669.rst b/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
 ========

diff --git a/peps/pep-0673.rst b/peps/pep-0673.rst
@@ -12,7 +12,8 @@ Python-Version: 3.11
 Post-History: 17-Nov-2021
 Resolution: https://mail.python.org/archives/list/[email protected]/thread/J7BWL5KWOPQQK5KFWKENVLXW6UGSPTGI/
 
-.. canonical-typing-spec:: :ref:`typing:self`
+.. canonical-typing-spec::
+   :related: :ref:`typing:self`
 
 Abstract
 ========

diff --git a/peps/pep-0675.rst b/peps/pep-0675.rst
@@ -11,7 +11,8 @@ Python-Version: 3.11
 Post-History: 07-Feb-2022
 Resolution: https://mail.python.org/archives/list/[email protected]/message/XEOOSSPNYPGZ5NXOJFPLXG2BTN7EVRT5/
 
-.. canonical-typing-spec:: :ref:`typing:literalstring`
+.. canonical-typing-spec::
+   :related: :ref:`typing:literalstring`
 
 Abstract
 ========