From 962a7ca61abbcdf917ea6504b0af6d7b952f4ef5 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Thu, 23 Jan 2025 04:04:32 +0000 Subject: [PATCH] Rename the ``:nowrap`` and ``:nosignatures:`` directive options --- CHANGES.rst | 5 +++++ doc/usage/extensions/autosummary.rst | 10 +++++++++- doc/usage/restructuredtext/directives.rst | 12 ++++++++++-- sphinx/directives/patches.py | 3 ++- sphinx/ext/autosummary/__init__.py | 5 +++-- sphinx/ext/imgmath.py | 2 +- sphinx/ext/mathjax.py | 2 +- sphinx/writers/latex.py | 2 +- tests/roots/test-ext-autosummary-ext/index.rst | 2 +- tests/roots/test-ext-math/math.rst | 2 +- tests/roots/test-root/math.txt | 2 +- 11 files changed, 35 insertions(+), 12 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 6271505bcc8..25ec405b9df 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -60,6 +60,11 @@ Features added :confval:`python_trailing_comma_in_multi_line_signatures` and :confval:`javascript_trailing_comma_in_multi_line_signatures` configuration options. +* #13264: Rename the :rst:dir:`math` directive's ``nowrap``option + to :rst:dir:`no-wrap``, + and rename the :rst:dir:`autosummary` directive's ``nosignatures``option + to :rst:dir:`no-signatures``. + Patch by Adam Turner. Bugs fixed ---------- diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index 3f6f656f37f..abff002ab4d 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -102,12 +102,20 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: .. versionadded:: 3.1 - .. rst:directive:option:: nosignatures + .. rst:directive:option:: no-signatures Do not show function signatures in the summary. .. versionadded:: 0.6 + .. versionchanged:: 8.2 + + The directive option ``:nosignatures:`` was renamed to ``:no-signatures:``. + + The previous name has been retained as an alias, + but will be deprecated and removed + in a future version of Sphinx. + .. rst:directive:option:: template: filename Specify a custom template for rendering the summary. diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index 441f225b877..a2b2fc638a8 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -1553,7 +1553,7 @@ or use Python raw strings (``r"raw"``). number to be issued. See :rst:role:`eq` for an example. The numbering style depends on the output format. - .. rst:directive:option:: nowrap + .. rst:directive:option:: no-wrap Prevent wrapping of the given math in a math environment. When you give this option, you must make sure @@ -1561,13 +1561,21 @@ or use Python raw strings (``r"raw"``). For example:: .. math:: - :nowrap: + :no-wrap: \begin{eqnarray} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{eqnarray} + .. versionchanged:: 8.2 + + The directive option ``:nowrap:`` was renamed to ``:no-wrap:``. + + The previous name has been retained as an alias, + but will be deprecated and removed + in a future version of Sphinx. + .. _AmSMath LaTeX package: https://www.ams.org/publications/authors/tex/amslatex .. seealso:: diff --git a/sphinx/directives/patches.py b/sphinx/directives/patches.py index b09db875d4e..0d52fe96b4c 100644 --- a/sphinx/directives/patches.py +++ b/sphinx/directives/patches.py @@ -143,6 +143,7 @@ class MathDirective(SphinxDirective): 'label': directives.unchanged, 'name': directives.unchanged, 'class': directives.class_option, + 'no-wrap': directives.flag, 'nowrap': directives.flag, } @@ -158,7 +159,7 @@ def run(self) -> list[Node]: docname=self.env.docname, number=None, label=label, - nowrap='nowrap' in self.options, + nowrap='no-wrap' in self.options or 'nowrap' in self.options, ) self.add_name(node) self.set_source_info(node) diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 23efcc88ced..e29b62f976e 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -237,9 +237,10 @@ class Autosummary(SphinxDirective): 'caption': directives.unchanged_required, 'class': directives.class_option, 'toctree': directives.unchanged, - 'nosignatures': directives.flag, + 'no-signatures': directives.flag, 'recursive': directives.flag, 'template': directives.unchanged, + 'nosignatures': directives.flag, } def run(self) -> list[Node]: @@ -462,7 +463,7 @@ def append_row(*column_texts: str) -> None: for name, sig, summary, real_name in items: qualifier = 'obj' - if 'nosignatures' not in self.options: + if 'no-signatures' not in self.options and 'nosignatures' not in self.options: col1 = f':py:{qualifier}:`{name} <{real_name}>`\\ {rst.escape(sig)}' else: col1 = f':py:{qualifier}:`{name} <{real_name}>`' diff --git a/sphinx/ext/imgmath.py b/sphinx/ext/imgmath.py index 3b379bc52cf..2fde626fd06 100644 --- a/sphinx/ext/imgmath.py +++ b/sphinx/ext/imgmath.py @@ -366,7 +366,7 @@ def html_visit_math(self: HTML5Translator, node: nodes.math) -> None: def html_visit_displaymath(self: HTML5Translator, node: nodes.math_block) -> None: - if node['nowrap']: + if node['no-wrap'] or node['nowrap']: latex = node.astext() else: latex = wrap_displaymath(node.astext(), None, False) diff --git a/sphinx/ext/mathjax.py b/sphinx/ext/mathjax.py index c730a559c79..99f9e173eee 100644 --- a/sphinx/ext/mathjax.py +++ b/sphinx/ext/mathjax.py @@ -47,7 +47,7 @@ def html_visit_math(self: HTML5Translator, node: nodes.math) -> None: def html_visit_displaymath(self: HTML5Translator, node: nodes.math_block) -> None: self.body.append(self.starttag(node, 'div', CLASS='math notranslate nohighlight')) - if node['nowrap']: + if node['no-wrap'] or node['nowrap']: self.body.append(self.encode(node.astext())) self.body.append('') raise nodes.SkipNode diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index f30eff2bf8c..8f9f6998f63 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -2465,7 +2465,7 @@ def visit_math_block(self, node: nodes.math_block) -> None: else: label = None - if node.get('nowrap'): + if node.get('no-wrap', False) or node.get('nowrap', False): if label: self.body.append(r'\label{%s}' % label) self.body.append(node.astext()) diff --git a/tests/roots/test-ext-autosummary-ext/index.rst b/tests/roots/test-ext-autosummary-ext/index.rst index 5ddc4bd40fe..1a7bb2177c6 100644 --- a/tests/roots/test-ext-autosummary-ext/index.rst +++ b/tests/roots/test-ext-autosummary-ext/index.rst @@ -1,6 +1,6 @@ .. autosummary:: - :nosignatures: + :no-signatures: :toctree: dummy_module diff --git a/tests/roots/test-ext-math/math.rst b/tests/roots/test-ext-math/math.rst index c05c3a05367..8a186d1b2cd 100644 --- a/tests/roots/test-ext-math/math.rst +++ b/tests/roots/test-ext-math/math.rst @@ -24,7 +24,7 @@ This is inline math: :math:`a^2 + b^2 = c^2`. n \in \mathbb N .. math:: - :nowrap: + :no-wrap: a + 1 < b diff --git a/tests/roots/test-root/math.txt b/tests/roots/test-root/math.txt index 5a209bed43b..11664400779 100644 --- a/tests/roots/test-root/math.txt +++ b/tests/roots/test-root/math.txt @@ -24,7 +24,7 @@ This is inline math: :math:`a^2 + b^2 = c^2`. n \in \mathbb N .. math:: - :nowrap: + :no-wrap: a + 1 < b