Allow configuring the separator used in numbering equations (#12523)

Co-authored-by: Thomas Fanning <[email protected]>
Co-authored-by: Adam Turner <[email protected]>

Author: 3 people

CHANGES.rst

@@ -68,6 +68,9 @@ Features added
   and :confval:`texinfo_domain_indices`,
   can now be a set of strings.
   Patch by Adam Turner.
+* #12523: Added configuration option, :confval:`math_numsep`, to define the
+  separator for math numbering.
+  Patch by Thomas Fanning
 
 Bugs fixed
 ----------

doc/usage/configuration.rst

@@ -906,6 +906,18 @@ These options control maths markup and notation.
 
    .. versionadded:: 1.7
 
+.. confval:: math_numsep
+   :type: :code-py:`str`
+   :default: :code-py:`'.'`
+
+   A string that defines the separator between section numbers
+   and the equation number when :confval:`numfig` is enabled and
+   :confval:`numfig_secnum_depth` is positive.
+
+   Example: :code-py:`'-'` gets rendered as ``1.2-3``.
+
+   .. versionadded:: 7.4
+
 
 Options for the nitpicky mode
 -----------------------------

sphinx/config.py

@@ -258,6 +258,7 @@ class Config:
         'math_number_all': _Opt(False, 'env', ()),
         'math_eqref_format': _Opt(None, 'env', frozenset((str,))),
         'math_numfig': _Opt(True, 'env', ()),
+        'math_numsep': _Opt('.', 'env', frozenset((str,))),
         'tls_verify': _Opt(True, 'env', ()),
         'tls_cacerts': _Opt(None, 'env', ()),
         'user_agent': _Opt(None, 'env', frozenset((str,))),

sphinx/domains/math.py

@@ -106,6 +106,7 @@ def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder
                 if docname in env.toc_fignumbers:
                     numbers = env.toc_fignumbers[docname]['displaymath'].get(node_id, ())
                     eqno = '.'.join(map(str, numbers))
+                    eqno = env.config.math_numsep.join(eqno.rsplit('.', 1))
                 else:
                     eqno = ''
             else:

sphinx/util/math.py

@@ -20,7 +20,9 @@ def get_node_equation_number(writer: HTML5Translator, node: nodes.math_block) ->
 
         id = node['ids'][0]
         number = writer.builder.fignumbers.get(key, {}).get(id, ())
-        return '.'.join(map(str, number))
+        eqno = '.'.join(map(str, number))
+        eqno = writer.builder.config.math_numsep.join(eqno.rsplit('.', 1))
+        return eqno
     else:
         return node['number']
 

tests/test_extensions/test_ext_math.py

@@ -193,6 +193,24 @@ def test_mathjax_numfig_html(app, status, warning):
     assert html in content
 
 
+@pytest.mark.sphinx('html', testroot='ext-math',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax'],
+                                   'numfig': True,
+                                   'math_numfig': True,
+                                   'math_numsep': '-'})
+def test_mathjax_numsep_html(app, status, warning):
+    app.build(force_all=True)
+
+    content = (app.outdir / 'math.html').read_text(encoding='utf8')
+    html = ('<div class="math notranslate nohighlight" id="equation-math-0">\n'
+            '<span class="eqno">(1-2)')
+    assert html in content
+    html = ('<p>Referencing equation <a class="reference internal" '
+            'href="#equation-foo">(1-1)</a> and '
+            '<a class="reference internal" href="#equation-foo">(1-1)</a>.</p>')
+    assert html in content
+
+
 @pytest.mark.sphinx('html', testroot='ext-math',
                     confoverrides={'extensions': ['sphinx.ext.imgmath'],
                                    'numfig': True,