Skip to content

Commit

Permalink
Use an option instead of argument in banner directives
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
pradyunsg committed Apr 28, 2024
1 parent 72595af commit 13144fb
Show file tree
Hide file tree
Showing 45 changed files with 112 additions and 64 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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/"
Expand All @@ -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 = ""
Expand All @@ -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:

Check warning on line 30 in pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py

View check run for this annotation

Codecov / codecov/patch

pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py#L30

Added line #L30 was not covered by tests
pre_text = self.admonition_pre_template.format(
link_content=link_content)
link_content=self.options['related'])
else:
pre_text = self.admonition_pre_text

Expand Down
18 changes: 12 additions & 6 deletions peps/pep-0012.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0215.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ Python-Version: 2.1
Post-History:
Superseded-By: 292

.. superseded:: 292
.. superseded::
:related: 292

Abstract
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0241.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
============
Expand Down
5 changes: 3 additions & 2 deletions peps/pep-0384.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0425.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0427.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0440.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0544.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 3 additions & 2 deletions peps/pep-0560.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0566.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0586.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0589.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0591.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0593.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0604.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0610.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0612.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0613.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0617.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0621.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0627.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0630.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0634.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0643.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0647.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
5 changes: 3 additions & 2 deletions peps/pep-0652.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0654.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0655.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0668.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0669.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0673.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
3 changes: 2 additions & 1 deletion peps/pep-0675.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand Down
Loading

0 comments on commit 13144fb

Please sign in to comment.