Rename the :nowrap and :nosignatures: directive options (sphinx-doc#13264)

Rename the ``:nowrap`` and ``:nosignatures:`` directive options to
``:no-wrap`` and ``:no-signatures:``, for readability.
This mirrors changes already made to `:no-index`, `:no-index-entry`,
`:no-contents-entry`, and `:no-search` in Sphinx 7.2 and 7.3.

Author: AA-Turner

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
 ----------

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.

doc/usage/restructuredtext/directives.rst

@@ -1553,21 +1553,29 @@ 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
       yourself that the math is properly set up.
       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::

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)
 

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}>`'

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)

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('</div>')
         raise nodes.SkipNode

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())

tests/roots/test-ext-autosummary-ext/index.rst

@@ -1,6 +1,6 @@
 
 .. autosummary::
-   :nosignatures:
+   :no-signatures:
    :toctree:
 
    dummy_module

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