Skip to content

Commit 13144fb

Browse files
pradyunsgpradyunsg
committed
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.
1 parent 72595af commit 13144fb

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+112
-64
lines changed

‎pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py

+6-7
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
from docutils import nodes
66
from docutils.parsers import rst
7+
from docutils.parsers.rst import directives
78

89
PYPA_SPEC_BASE_URL = "https://packaging.python.org/en/latest/specifications/"
910
TYPING_SPEC_BASE_URL = "https://typing.readthedocs.io/en/latest/spec/"
@@ -14,9 +15,9 @@ class PEPBanner(rst.Directive):
1415

1516
has_content = True
1617
required_arguments = 0
17-
optional_arguments = 1
18-
final_argument_whitespace = True
19-
option_spec = {}
18+
option_spec = {
19+
'related': directives.unchanged,
20+
}
2021

2122
admonition_pre_template = ""
2223
admonition_pre_text = ""
@@ -26,11 +27,9 @@ class PEPBanner(rst.Directive):
2627
css_classes = []
2728

2829
def run(self) -> list[nodes.admonition]:
29-
30-
if self.arguments:
31-
link_content = self.arguments[0]
30+
if 'related' in self.options:
3231
pre_text = self.admonition_pre_template.format(
33-
link_content=link_content)
32+
link_content=self.options['related'])
3433
else:
3534
pre_text = self.admonition_pre_text
3635

‎peps/pep-0012.rst

+12-6
Original file line numberDiff line numberDiff line change
@@ -677,34 +677,40 @@ For example,
677677
to create a banner pointing to the :mod:`python:sqlite3` docs,
678678
you would write the following::
679679

680-
.. canonical-doc:: :mod:`python:sqlite3`
680+
.. canonical-doc::
681+
:related: :mod:`python:sqlite3`
681682

682683
which would generate the banner:
683684

684-
.. canonical-doc:: :mod:`python:sqlite3`
685+
.. canonical-doc::
686+
:related: :mod:`python:sqlite3`
685687

686688
Or for a PyPA spec,
687689
such as the :ref:`packaging:core-metadata`,
688690
you would use::
689691

690-
.. canonical-pypa-spec:: :ref:`packaging:core-metadata`
692+
.. canonical-pypa-spec::
693+
:related: :ref:`packaging:core-metadata`
691694

692695
which renders as:
693696

694-
.. canonical-pypa-spec:: :ref:`packaging:core-metadata`
697+
.. canonical-pypa-spec::
698+
:related: :ref:`packaging:core-metadata`
695699

696700
The argument accepts arbitrary reST,
697701
so you can include multiple linked docs/specs and name them whatever you like,
698702
and you can also include directive content that will be inserted into the text.
699703
The following advanced example::
700704

701-
.. canonical-doc:: the :ref:`python:sqlite3-connection-objects` and :exc:`python:~sqlite3.DataError` docs
705+
.. canonical-doc::
706+
:related: the :ref:`python:sqlite3-connection-objects` and :exc:`python:~sqlite3.DataError` docs
702707

703708
Also, see the :ref:`Data Persistence docs <persistence>` for other examples.
704709

705710
would render as:
706711

707-
.. canonical-doc:: the :ref:`python:sqlite3-connection-objects` and :exc:`python:sqlite3.DataError` docs
712+
.. canonical-doc::
713+
:related: the :ref:`python:sqlite3-connection-objects` and :exc:`python:sqlite3.DataError` docs
708714

709715
Also, see the :ref:`Data Persistence docs <persistence>` for other examples.
710716

‎peps/pep-0215.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@ Python-Version: 2.1
88
Post-History:
99
Superseded-By: 292
1010

11-
.. superseded:: 292
11+
.. superseded::
12+
:related: 292
1213

1314
Abstract
1415
========

‎peps/pep-0241.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ Created: 12-Mar-2001
99
Post-History: `19-Mar-2001 <https://mail.python.org/archives/list/[email protected]/thread/46XPDHQHI3XAAJHEZAMAMKZYAI6K7NB6/>`__
1010
Superseded-By: 314
1111

12-
.. superseded:: 314
12+
.. superseded::
13+
:related: 314
1314

1415
Introduction
1516
============

‎peps/pep-0384.rst

+3-2
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,9 @@ Created: 17-May-2009
88
Python-Version: 3.2
99
Post-History:
1010

11-
.. canonical-doc:: :ref:`python:stable` (user docs) and
12-
:ref:`devguide:c-api` (development docs)
11+
.. canonical-doc::
12+
:related: :ref:`python:stable` (user docs) and
13+
:ref:`devguide:c-api` (development docs)
1314

1415
Abstract
1516
========

‎peps/pep-0425.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ Post-History: 08-Aug-2012, 18-Oct-2012, 15-Feb-2013
1414
Resolution: https://mail.python.org/pipermail/python-dev/2013-February/124116.html
1515

1616

17-
.. canonical-pypa-spec:: :ref:`packaging:platform-compatibility-tags`
17+
.. canonical-pypa-spec::
18+
:related: :ref:`packaging:platform-compatibility-tags`
1819

1920

2021
Abstract

‎peps/pep-0427.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ Post-History: 18-Oct-2012, 15-Feb-2013
1414
Resolution: https://mail.python.org/pipermail/python-dev/2013-February/124103.html
1515

1616

17-
.. canonical-pypa-spec:: :ref:`packaging:binary-distribution-format`
17+
.. canonical-pypa-spec::
18+
:related: :ref:`packaging:binary-distribution-format`
1819

1920

2021
Abstract

‎peps/pep-0440.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ Post-History: 30-Mar-2013, 27-May-2013, 20-Jun-2013,
1515
Replaces: 386
1616
Resolution: https://mail.python.org/pipermail/distutils-sig/2014-August/024673.html
1717

18-
.. canonical-pypa-spec:: :ref:`version-specifiers`
18+
.. canonical-pypa-spec::
19+
:related: :ref:`version-specifiers`
1920

2021

2122
Abstract

‎peps/pep-0544.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ Created: 05-Mar-2017
1010
Python-Version: 3.8
1111
Resolution: https://mail.python.org/archives/list/[email protected]/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
1212

13-
.. canonical-typing-spec:: :ref:`typing:protocols`
13+
.. canonical-typing-spec::
14+
:related: :ref:`typing:protocols`
1415

1516

1617
Abstract

‎peps/pep-0560.rst

+3-2
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,9 @@ Python-Version: 3.7
99
Post-History: 09-Sep-2017, 14-Nov-2017
1010
Resolution: https://mail.python.org/pipermail/python-dev/2017-December/151038.html
1111

12-
.. canonical-doc:: :external+python:meth:`object.__class_getitem__` and
13-
:external+python:meth:`object.__mro_entries__`
12+
.. canonical-doc::
13+
:related: :external+python:meth:`object.__class_getitem__` and
14+
:external+python:meth:`object.__mro_entries__`
1415

1516
Abstract
1617
========

‎peps/pep-0566.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ Replaces: 345
1414
Resolution: https://mail.python.org/pipermail/distutils-sig/2018-February/032014.html
1515

1616

17-
.. canonical-pypa-spec:: :ref:`packaging:core-metadata`
17+
.. canonical-pypa-spec::
18+
:related: :ref:`packaging:core-metadata`
1819

1920

2021
Abstract

‎peps/pep-0586.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ Python-Version: 3.8
1111
Post-History: 14-Mar-2019
1212
Resolution: https://mail.python.org/archives/list/[email protected]/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
1313

14-
.. canonical-typing-spec:: :ref:`typing:literal-types`
14+
.. canonical-typing-spec::
15+
:related: :ref:`typing:literal-types`
1516

1617
Abstract
1718
========

‎peps/pep-0589.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ Python-Version: 3.8
1212
Post-History:
1313
Resolution: https://mail.python.org/archives/list/[email protected]/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
1414

15-
.. canonical-typing-spec:: :ref:`typing:typeddict`
15+
.. canonical-typing-spec::
16+
:related: :ref:`typing:typeddict`
1617

1718
Abstract
1819
========

‎peps/pep-0591.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ Python-Version: 3.8
1111
Post-History:
1212
Resolution: https://mail.python.org/archives/list/[email protected]/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
1313

14-
.. canonical-typing-spec:: :ref:`typing:at-final` and :ref:`typing:uppercase-final`
14+
.. canonical-typing-spec::
15+
:related: :ref:`typing:at-final` and :ref:`typing:uppercase-final`
1516

1617
Abstract
1718
========

‎peps/pep-0593.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ Created: 26-Apr-2019
1010
Python-Version: 3.9
1111
Post-History: 20-May-2019
1212

13-
.. canonical-typing-spec:: :ref:`annotated`
13+
.. canonical-typing-spec::
14+
:related: :ref:`annotated`
1415

1516
Abstract
1617
--------

‎peps/pep-0604.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ Created: 28-Aug-2019
1111
Python-Version: 3.10
1212
Post-History: 28-Aug-2019, 05-Aug-2020
1313

14-
.. canonical-doc:: :ref:`python:types-union`
14+
.. canonical-doc::
15+
:related: :ref:`python:types-union`
1516

1617
Abstract
1718
========

‎peps/pep-0610.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ Post-History:
1313
Resolution: https://discuss.python.org/t/1535/56
1414

1515

16-
.. canonical-pypa-spec:: :ref:`packaging:direct-url`
16+
.. canonical-pypa-spec::
17+
:related: :ref:`packaging:direct-url`
1718

1819

1920
Abstract

‎peps/pep-0612.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ Created: 18-Dec-2019
1111
Python-Version: 3.10
1212
Post-History: 18-Dec-2019, 13-Jul-2020
1313

14-
.. canonical-typing-spec:: :ref:`typing:paramspec`
14+
.. canonical-typing-spec::
15+
:related: :ref:`typing:paramspec`
1516

1617
Abstract
1718
--------

‎peps/pep-0613.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ Created: 21-Jan-2020
1010
Python-Version: 3.10
1111
Post-History: 21-Jan-2020
1212

13-
.. canonical-typing-spec:: :ref:`typing:type-aliases`
13+
.. canonical-typing-spec::
14+
:related: :ref:`typing:type-aliases`
1415

1516
Abstract
1617
========

‎peps/pep-0617.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ Created: 24-Mar-2020
1010
Python-Version: 3.9
1111
Post-History: 02-Apr-2020
1212

13-
.. canonical-doc:: :ref:`python:full-grammar-specification`
13+
.. canonical-doc::
14+
:related: :ref:`python:full-grammar-specification`
1415

1516
.. highlight:: PEG
1617

‎peps/pep-0621.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ Post-History: 22-Jun-2020,
2020
Resolution: https://discuss.python.org/t/pep-621-round-3/5472/109
2121

2222

23-
.. canonical-pypa-spec:: :ref:`packaging:pyproject-toml-spec`
23+
.. canonical-pypa-spec::
24+
:related: :ref:`packaging:pyproject-toml-spec`
2425

2526

2627
Abstract

‎peps/pep-0627.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ Created: 15-Jul-2020
1111
Resolution: https://discuss.python.org/t/pep-627/4126/42
1212

1313

14-
.. canonical-pypa-spec:: :ref:`packaging:recording-installed-packages`
14+
.. canonical-pypa-spec::
15+
:related: :ref:`packaging:recording-installed-packages`
1516

1617

1718
Abstract

‎peps/pep-0630.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ Post-History: 16-Jul-2020
1111

1212
.. highlight:: c
1313

14-
.. canonical-doc:: `Isolating Extension Modules HOWTO <https://docs.python.org/3.11/howto/isolating-extensions.html>`_
14+
.. canonical-doc::
15+
:related: `Isolating Extension Modules HOWTO <https://docs.python.org/3.11/howto/isolating-extensions.html>`_
1516

1617
Abstract
1718
========

‎peps/pep-0634.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ Post-History: 22-Oct-2020, 08-Feb-2021
1212
Replaces: 622
1313
Resolution: https://mail.python.org/archives/list/[email protected]/message/SQC2FTLFV5A7DV7RCEAR2I2IKJKGK7W3
1414

15-
.. canonical-doc:: :external+python:ref:`match`
15+
.. canonical-doc::
16+
:related: :external+python:ref:`match`
1617

1718
Abstract
1819
========

‎peps/pep-0643.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ Post-History: 24-Oct-2020, 01-Nov-2020, 02-Nov-2020, 14-Nov-2020
1212
Resolution: https://discuss.python.org/t/pep-643-metadata-for-package-source-distributions/5577/53
1313

1414

15-
.. canonical-pypa-spec:: :ref:`packaging:core-metadata`
15+
.. canonical-pypa-spec::
16+
:related: :ref:`packaging:core-metadata`
1617

1718

1819
Abstract

‎peps/pep-0647.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ Python-Version: 3.10
1111
Post-History: 28-Dec-2020, 09-Apr-2021
1212
Resolution: https://mail.python.org/archives/list/[email protected]/thread/2ME6F6YUVKHOQYKSHTVQQU5WD4CVAZU4/
1313

14-
.. canonical-typing-spec:: :ref:`typing:typeguard`
14+
.. canonical-typing-spec::
15+
:related: :ref:`typing:typeguard`
1516

1617
Abstract
1718
========

‎peps/pep-0652.rst

+3-2
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,9 @@ Python-Version: 3.10
1010
Resolution: https://mail.python.org/archives/list/[email protected]/message/IN4XMFLQJ6D6V67EXU27GV3QWSEHHNNH/
1111

1212

13-
.. canonical-doc:: :ref:`python:stable` (user docs) and
14-
:ref:`devguide:c-api` (development docs)
13+
.. canonical-doc::
14+
:related: :ref:`python:stable` (user docs) and
15+
:ref:`devguide:c-api` (development docs)
1516

1617
Abstract
1718
========

‎peps/pep-0654.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ Post-History: `22-Feb-2021 <https://mail.python.org/archives/list/python-dev@pyt
1414
`03-Oct-2021 <https://mail.python.org/archives/list/[email protected]/thread/4B256YKUPW5P2M44GG5H6FBL3PSV6ODP/>`__,
1515
Resolution: https://discuss.python.org/t/accepting-pep-654-exception-groups-and-except/10813/1
1616

17-
.. canonical-doc:: :ref:`python:lib-exception-groups` and :ref:`python:except_star`
17+
.. canonical-doc::
18+
:related: :ref:`python:lib-exception-groups` and :ref:`python:except_star`
1819

1920
See :ref:`python:tut-exception-groups` for a user-focused tutorial.
2021

‎peps/pep-0655.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ Python-Version: 3.11
1111
Post-History: 31-Jan-2021, 11-Feb-2021, 20-Feb-2021, 26-Feb-2021, 17-Jan-2022, 28-Jan-2022
1212
Resolution: https://mail.python.org/archives/list/[email protected]/message/AJEDNVC3FXM5QXNNW5CR4UCT4KI5XVUE/
1313

14-
.. canonical-typing-spec:: :ref:`typing:required-notrequired`
14+
.. canonical-typing-spec::
15+
:related: :ref:`typing:required-notrequired`
1516

1617
Abstract
1718
========

‎peps/pep-0668.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@ Created: 18-May-2021
1818
Post-History: 28-May-2021
1919
Resolution: https://discuss.python.org/t/10302/44
2020

21-
.. canonical-pypa-spec:: :ref:`externally-managed-environments`
21+
.. canonical-pypa-spec::
22+
:related: :ref:`externally-managed-environments`
2223

2324
Abstract
2425
========

‎peps/pep-0669.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ Post-History: `07-Dec-2021 <https://mail.python.org/archives/list/python-dev@pyt
1010
`10-Jan-2022 <https://discuss.python.org/t/pep-669-low-impact-monitoring-for-cpython/13018>`__,
1111
Resolution: https://discuss.python.org/t/pep-669-low-impact-monitoring-for-cpython/13018/42
1212

13-
.. canonical-doc:: :mod:`python:sys.monitoring`
13+
.. canonical-doc::
14+
:related: :mod:`python:sys.monitoring`
1415

1516
Abstract
1617
========

‎peps/pep-0673.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ Python-Version: 3.11
1212
Post-History: 17-Nov-2021
1313
Resolution: https://mail.python.org/archives/list/[email protected]/thread/J7BWL5KWOPQQK5KFWKENVLXW6UGSPTGI/
1414

15-
.. canonical-typing-spec:: :ref:`typing:self`
15+
.. canonical-typing-spec::
16+
:related: :ref:`typing:self`
1617

1718
Abstract
1819
========

‎peps/pep-0675.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ Python-Version: 3.11
1111
Post-History: 07-Feb-2022
1212
Resolution: https://mail.python.org/archives/list/[email protected]/message/XEOOSSPNYPGZ5NXOJFPLXG2BTN7EVRT5/
1313

14-
.. canonical-typing-spec:: :ref:`typing:literalstring`
14+
.. canonical-typing-spec::
15+
:related: :ref:`typing:literalstring`
1516

1617
Abstract
1718
========

0 commit comments

Comments
 (0)