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..94184de502c 100644 --- a/sphinx/directives/patches.py +++ b/sphinx/directives/patches.py @@ -143,10 +143,17 @@ class MathDirective(SphinxDirective): 'label': directives.unchanged, 'name': directives.unchanged, 'class': directives.class_option, + 'no-wrap': directives.flag, 'nowrap': directives.flag, } def run(self) -> list[Node]: + # Copy the old option name to the new one + # xref RemovedInSphinx90Warning + # deprecate nowrap in Sphinx 9.0 + if 'no-wrap' not in self.options and 'nowrap' in self.options: + self.options['no-wrap'] = self.options['nowrap'] + latex = '\n'.join(self.content) if self.arguments and self.arguments[0]: latex = self.arguments[0] + '\n\n' + latex @@ -158,8 +165,8 @@ def run(self) -> list[Node]: docname=self.env.docname, number=None, label=label, - nowrap='nowrap' in self.options, ) + node['no-wrap'] = node['nowrap'] = 'no-wrap' 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..ff83a4b1f0c 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -11,7 +11,7 @@ The autosummary directive has the form:: .. autosummary:: - :nosignatures: + :no-signatures: :toctree: generated/ module.function_1 @@ -237,12 +237,19 @@ 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]: + # Copy the old option name to the new one + # xref RemovedInSphinx90Warning + # deprecate nosignatures in Sphinx 9.0 + if 'no-signatures' not in self.options and 'nosignatures' in self.options: + self.options['no-signatures'] = self.options['nosignatures'] + self.bridge = DocumenterBridge( self.env, self.state.document.reporter, Options(), self.lineno, self.state ) @@ -462,7 +469,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: 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..b3592263690 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']: 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..c6a78344059 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'): 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