From a8a4bfb53f195710d6c9b3fe715d21d3b5fc9bdf Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 28 Apr 2024 18:46:45 +0100 Subject: [PATCH 1/2] 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. --- .../parsing/pep_banner_directive.py | 13 ++++++------- peps/pep-0012.rst | 18 ++++++++++++------ peps/pep-0215.rst | 3 ++- peps/pep-0241.rst | 3 ++- peps/pep-0384.rst | 5 +++-- peps/pep-0425.rst | 3 ++- peps/pep-0427.rst | 3 ++- peps/pep-0440.rst | 3 ++- peps/pep-0544.rst | 3 ++- peps/pep-0560.rst | 5 +++-- peps/pep-0566.rst | 3 ++- peps/pep-0586.rst | 3 ++- peps/pep-0589.rst | 3 ++- peps/pep-0591.rst | 3 ++- peps/pep-0593.rst | 3 ++- peps/pep-0604.rst | 3 ++- peps/pep-0610.rst | 3 ++- peps/pep-0612.rst | 3 ++- peps/pep-0613.rst | 3 ++- peps/pep-0617.rst | 3 ++- peps/pep-0621.rst | 3 ++- peps/pep-0627.rst | 3 ++- peps/pep-0630.rst | 3 ++- peps/pep-0634.rst | 3 ++- peps/pep-0643.rst | 3 ++- peps/pep-0647.rst | 3 ++- peps/pep-0652.rst | 5 +++-- peps/pep-0654.rst | 3 ++- peps/pep-0655.rst | 3 ++- peps/pep-0668.rst | 3 ++- peps/pep-0669.rst | 3 ++- peps/pep-0673.rst | 3 ++- peps/pep-0675.rst | 3 ++- peps/pep-0678.rst | 3 ++- peps/pep-0680.rst | 3 ++- peps/pep-0681.rst | 3 ++- peps/pep-0688.rst | 3 ++- peps/pep-0689.rst | 3 ++- peps/pep-0692.rst | 3 ++- peps/pep-0695.rst | 11 ++++++----- peps/pep-0698.rst | 3 ++- peps/pep-0700.rst | 3 ++- peps/pep-0706.rst | 3 ++- peps/pep-0721.rst | 3 ++- peps/pep-3121.rst | 5 +++-- 45 files changed, 112 insertions(+), 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 index fa147578775..4422fabefe7 100644 --- 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 index 8f684fdf0f1..f283b155444 100644 --- 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 ` 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 ` for other examples. diff --git a/peps/pep-0215.rst b/peps/pep-0215.rst index df51b07ea08..63b11730f8b 100644 --- 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 index a33fe482647..4ba21ea0ee8 100644 --- a/peps/pep-0241.rst +++ b/peps/pep-0241.rst @@ -9,7 +9,8 @@ Created: 12-Mar-2001 Post-History: `19-Mar-2001 `__ Superseded-By: 314 -.. superseded:: 314 +.. superseded:: + :related: 314 Introduction ============ diff --git a/peps/pep-0384.rst b/peps/pep-0384.rst index 867173da92d..79803e4c815 100644 --- 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 index d1fd39d1705..859ab7f84de 100644 --- 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 index 921a6258ccf..ab5c317c84b 100644 --- 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 index 16d767c03f4..142e7d23856 100644 --- 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 index 039cffa73c9..b4bc3cafb59 100644 --- 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/typing-sig@python.org/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 index 2626238643f..a49734b9b0b 100644 --- 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 index ff20cf4e812..84e7e5d519f 100644 --- 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 index 99fe92ca8df..7d008cb6bba 100644 --- 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/typing-sig@python.org/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 index d4b07b45a0a..836f4e15e20 100644 --- 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/typing-sig@python.org/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 index e19260f176c..79a97935eef 100644 --- 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/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 ======== diff --git a/peps/pep-0593.rst b/peps/pep-0593.rst index d7072f7a52b..945e2d3623d 100644 --- 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 index 1757cfda217..96fc06a3fca 100644 --- 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 index bfd2f0dd513..5f6708f5101 100644 --- 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 index 78aac53b30c..6debb8941fc 100644 --- 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 index 108cd958389..af221e03087 100644 --- 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 index 8de9ca913f9..eb024c9151c 100644 --- 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 index 2ad264757bd..a5f6eb096e4 100644 --- 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 index 81a13d72df5..7ee6038b843 100644 --- 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 index 9dfdef56b60..eb03a432e8b 100644 --- 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 `_ +.. canonical-doc:: + :related: `Isolating Extension Modules HOWTO `_ Abstract ======== diff --git a/peps/pep-0634.rst b/peps/pep-0634.rst index 8b35cce35fe..9a2a61cce5e 100644 --- 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/python-committers@python.org/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 index 08fc1f67551..be3535cf784 100644 --- 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 index 8d1131106bd..7fce41f3fe7 100644 --- 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/python-dev@python.org/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 index 19bdff9793a..382e47665a9 100644 --- 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/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 ======== diff --git a/peps/pep-0654.rst b/peps/pep-0654.rst index a7bb82a44a5..00df228e6ff 100644 --- a/peps/pep-0654.rst +++ b/peps/pep-0654.rst @@ -14,7 +14,8 @@ Post-History: `22-Feb-2021 `__, 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 index 1590a3a2d6c..81c8caec593 100644 --- 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/python-dev@python.org/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 index e3e7f43d3ed..93bcf847fca 100644 --- 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 index 3aee69bfbfe..2f606bd4833 100644 --- a/peps/pep-0669.rst +++ b/peps/pep-0669.rst @@ -10,7 +10,8 @@ Post-History: `07-Dec-2021 `__, 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 index 89408c420d4..1698ef6f4f7 100644 --- 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/python-dev@python.org/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 index 9cf7ab3ec74..bb59305bc12 100644 --- 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/python-dev@python.org/message/XEOOSSPNYPGZ5NXOJFPLXG2BTN7EVRT5/ -.. canonical-typing-spec:: :ref:`typing:literalstring` +.. canonical-typing-spec:: + :related: :ref:`typing:literalstring` Abstract ======== diff --git a/peps/pep-0678.rst b/peps/pep-0678.rst index 0e27b0245b7..1d7008e0bff 100644 --- a/peps/pep-0678.rst +++ b/peps/pep-0678.rst @@ -12,7 +12,8 @@ Python-Version: 3.11 Post-History: `27-Jan-2022 `__ Resolution: https://discuss.python.org/t/pep-678-enriching-exceptions-with-notes/13374/100 -.. canonical-doc:: :meth:`python:BaseException.add_note` and :attr:`python:BaseException.__notes__` +.. canonical-doc:: + :related: :meth:`python:BaseException.add_note` and :attr:`python:BaseException.__notes__` See :ref:`python:tut-exception-notes` for a user-focused tutorial. diff --git a/peps/pep-0680.rst b/peps/pep-0680.rst index d709d4fdb56..b21c64a85bb 100644 --- a/peps/pep-0680.rst +++ b/peps/pep-0680.rst @@ -12,7 +12,8 @@ Post-History: `09-Dec-2021 `__, Resolution: https://mail.python.org/archives/list/python-dev@python.org/thread/3AHGWYY562HHO55L4Z2OVYUFZP5W73IS/ -.. canonical-doc:: :mod:`python:tomllib` +.. canonical-doc:: + :related: :mod:`python:tomllib` Abstract ======== diff --git a/peps/pep-0681.rst b/peps/pep-0681.rst index 8f7450e7062..becdd40b246 100644 --- a/peps/pep-0681.rst +++ b/peps/pep-0681.rst @@ -14,7 +14,8 @@ Post-History: `24-Apr-2021 `__ Resolution: https://mail.python.org/archives/list/python-dev@python.org/message/R4A2IYLGFHKFDYJPSDA5NFJ6N7KRPJ6D/ -.. canonical-typing-spec:: :ref:`typing:dataclass-transform` +.. canonical-typing-spec:: + :related: :ref:`typing:dataclass-transform` Abstract ======== diff --git a/peps/pep-0688.rst b/peps/pep-0688.rst index 69183090ae0..4debaea46e1 100644 --- a/peps/pep-0688.rst +++ b/peps/pep-0688.rst @@ -13,7 +13,8 @@ Post-History: `23-Apr-2022 `__ Resolution: https://discuss.python.org/t/pep-688-making-the-buffer-protocol-accessible-in-python/15265/35 -.. canonical-doc:: :ref:`python:python-buffer-protocol` +.. canonical-doc:: + :related: :ref:`python:python-buffer-protocol` Abstract ======== diff --git a/peps/pep-0689.rst b/peps/pep-0689.rst index 01cf6f2696e..004597483b7 100644 --- a/peps/pep-0689.rst +++ b/peps/pep-0689.rst @@ -13,7 +13,8 @@ Post-History: `27-Apr-2022 `__, Resolution: https://discuss.python.org/t/pep-689-unstable-c-api-tier/20452/13 -.. canonical-doc:: :ref:`devguide:c-api` +.. canonical-doc:: + :related: :ref:`devguide:c-api` User-facing documentation is at :ref:`py3.12:unstable-c-api`. diff --git a/peps/pep-0692.rst b/peps/pep-0692.rst index 7b1f8d0a5be..01a71d65bbd 100644 --- a/peps/pep-0692.rst +++ b/peps/pep-0692.rst @@ -13,7 +13,8 @@ Post-History: `29-May-2022 `__, Resolution: https://discuss.python.org/t/pep-692-using-typeddict-for-more-precise-kwargs-typing/17314/81 -.. canonical-typing-spec:: :ref:`typing:unpack-kwargs` +.. canonical-typing-spec:: + :related: :ref:`typing:unpack-kwargs` Abstract ======== diff --git a/peps/pep-0695.rst b/peps/pep-0695.rst index e8b9a3650d6..34615bdfea5 100644 --- a/peps/pep-0695.rst +++ b/peps/pep-0695.rst @@ -12,11 +12,12 @@ Post-History: `20-Jun-2022 `__ Resolution: https://discuss.python.org/t/pep-695-type-parameter-syntax/21646/92 -.. canonical-typing-spec:: :ref:`typing:variance-inference`, - :ref:`typing:type-aliases`, - :ref:`python:type-params`, - :ref:`python:type` and - :ref:`python:annotation-scopes`. +.. canonical-typing-spec:: + :related: :ref:`typing:variance-inference`, + :ref:`typing:type-aliases`, + :ref:`python:type-params`, + :ref:`python:type` and + :ref:`python:annotation-scopes`. Abstract ======== diff --git a/peps/pep-0698.rst b/peps/pep-0698.rst index 7f83ef1a522..d2722831127 100644 --- a/peps/pep-0698.rst +++ b/peps/pep-0698.rst @@ -16,7 +16,8 @@ Post-History: `20-May-2022 `__, Resolution: https://discuss.python.org/t/pep-698-a-typing-override-decorator/20839/11 -.. canonical-typing-spec:: :ref:`typing:override` +.. canonical-typing-spec:: + :related: :ref:`typing:override` Abstract ======== diff --git a/peps/pep-0700.rst b/peps/pep-0700.rst index e2be354567e..d8a6f7fd62c 100644 --- a/peps/pep-0700.rst +++ b/peps/pep-0700.rst @@ -10,7 +10,8 @@ Created: 21-Oct-2022 Post-History: `21-Oct-2022 `__ Resolution: https://discuss.python.org/t/pep-700-additional-fields-for-the-simple-api-for-package-indexes/20177/42 -.. canonical-pypa-spec:: :ref:`packaging:simple-repository-api` +.. canonical-pypa-spec:: + :related: :ref:`packaging:simple-repository-api` Abstract ======== diff --git a/peps/pep-0706.rst b/peps/pep-0706.rst index 5585a809b03..3d5affe77b6 100644 --- a/peps/pep-0706.rst +++ b/peps/pep-0706.rst @@ -11,7 +11,8 @@ Post-History: `25-Jan-2023 `__, `15-Feb-2023 `__, Resolution: https://discuss.python.org/t/23903/10 -.. canonical-doc:: :ref:`tarfile documentation ` +.. canonical-doc:: + :related: :ref:`tarfile documentation ` Abstract diff --git a/peps/pep-0721.rst b/peps/pep-0721.rst index 5c2375f6152..c18b00aa5fc 100644 --- a/peps/pep-0721.rst +++ b/peps/pep-0721.rst @@ -12,7 +12,8 @@ Python-Version: 3.12 Post-History: `04-Jul-2023 `__, Resolution: https://discuss.python.org/t/28928/13 -.. canonical-pypa-spec:: :ref:`packaging:sdist-archive-features` +.. canonical-pypa-spec:: + :related: :ref:`packaging:sdist-archive-features` Abstract ======== diff --git a/peps/pep-3121.rst b/peps/pep-3121.rst index 047391efe75..901508356a8 100644 --- a/peps/pep-3121.rst +++ b/peps/pep-3121.rst @@ -10,8 +10,9 @@ Created: 27-Apr-2007 Python-Version: 3.0 Post-History: -.. canonical-doc:: :external+python:c:func:`PyInit_modulename` and - :external+python:c:type:`PyModuleDef` +.. canonical-doc:: + :related: :external+python:c:func:`PyInit_modulename` and + :external+python:c:type:`PyModuleDef` Abstract ======== From 76b1aa3ee1ace53c6277b194769ce9c553af6440 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Mon, 6 May 2024 10:22:30 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- .../pep_processor/parsing/pep_banner_directive.py | 4 ++-- 1 file changed, 2 insertions(+), 2 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 index 4422fabefe7..fcf1bb2dc23 100644 --- a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py +++ b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py @@ -27,9 +27,9 @@ class PEPBanner(rst.Directive): css_classes = [] def run(self) -> list[nodes.admonition]: - if 'related' in self.options: + if link_content := self.options.get('related', ''): pre_text = self.admonition_pre_template.format( - link_content=self.options['related']) + link_content=link_content) else: pre_text = self.admonition_pre_text