Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Infra: Use an option instead of argument in banner directives #3765

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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 @@

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 @@
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
pradyunsg marked this conversation as resolved.
Show resolved Hide resolved
pre_text = self.admonition_pre_template.format(
link_content=link_content)
link_content=self.options['related'])
pradyunsg marked this conversation as resolved.
Show resolved Hide resolved
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
Loading