Fix #3638: Allow to change a label of reference to equation

4 files changed, 56 insertions, 2 deletions

diff --git a/CHANGES b/CHANGES
index 2435523f4..d8f98b995 100644
--- a/CHANGES
+++ b/CHANGES
@@ -10,6 +10,9 @@ Deprecated
 Features added
 --------------
 
+* #3638: Allow to change a label of reference to equation using
+  ``math_eqref_format``
+
 Bugs fixed
 ----------
 
diff --git a/doc/ext/math.rst b/doc/ext/math.rst
index 56a44a217..dace54964 100644
--- a/doc/ext/math.rst
+++ b/doc/ext/math.rst
@@ -35,6 +35,13 @@ or use Python raw strings (``r"raw"``).
    Set this option to ``True`` if you want all displayed math to be numbered.
    The default is ``False``.
 
+.. confval:: math_eqref_format
+
+   A string that are used for format of label of references to equations.
+   As a special character, ``{number}`` will be replaced to equaition number.
+
+   Example: ``'Eq.{number}'`` is rendered as ``Eq.10``
+
 :mod:`.mathbase` defines these new markup elements:
 
 .. rst:role:: math
diff --git a/sphinx/ext/mathbase.py b/sphinx/ext/mathbase.py
index 9ca81d738..d4833e976 100644
--- a/sphinx/ext/mathbase.py
+++ b/sphinx/ext/mathbase.py
@@ -12,9 +12,11 @@
 from docutils import nodes, utils
 from docutils.parsers.rst import Directive, directives
 
+from sphinx.config import string_classes
 from sphinx.roles import XRefRole
 from sphinx.locale import _
 from sphinx.domains import Domain
+from sphinx.util import logging
 from sphinx.util.nodes import make_refnode, set_source_info
 
 if False:
@@ -25,6 +27,8 @@ if False:
     from sphinx.builders import Builder  # NOQA
     from sphinx.environment import BuildEnvironment  # NOQA
 
+logger = logging.getLogger(__name__)
+
 
 class math(nodes.Inline, nodes.TextElement):
     pass
@@ -80,7 +84,13 @@ class MathDomain(Domain):
                 newnode['target'] = target
                 return newnode
             else:
-                title = nodes.Text("(%d)" % number)
+                try:
+                    eqref_format = env.config.math_eqref_format or "({number})"
+                    title = nodes.Text(eqref_format.format(number=number))
+                except KeyError as exc:
+                    logger.warning('Invalid math_eqref_format: %r', exc,
+                                   location=node)
+                    title = nodes.Text("(%d)" % number)
                 return make_refnode(builder, fromdocname, docname,
                                     "equation-" + target, title)
         else:
@@ -264,7 +274,17 @@ def latex_visit_displaymath(self, node):
 def latex_visit_eqref(self, node):
     # type: (nodes.NodeVisitor, eqref) -> None
     label = "equation:%s:%s" % (node['docname'], node['target'])
-    self.body.append('\\eqref{%s}' % label)
+    eqref_format = self.builder.config.math_eqref_format
+    if eqref_format:
+        try:
+            ref = '\\ref{%s}' % label
+            self.body.append(eqref_format.format(number=ref))
+        except KeyError as exc:
+            logger.warning('Invalid math_eqref_format: %r', exc,
+                           location=node)
+            self.body.append('\\eqref{%s}' % label)
+    else:
+        self.body.append('\\eqref{%s}' % label)
     raise nodes.SkipNode
 
 
@@ -320,6 +340,7 @@ def texinfo_depart_displaymath(self, node):
 def setup_math(app, htmlinlinevisitors, htmldisplayvisitors):
     # type: (Sphinx, Tuple[Callable, Any], Tuple[Callable, Any]) -> None
     app.add_config_value('math_number_all', False, 'env')
+    app.add_config_value('math_eqref_format', None, 'env', string_classes)
     app.add_domain(MathDomain)
     app.add_node(math, override=True,
                  latex=(latex_visit_math, None),
diff --git a/tests/test_ext_math.py b/tests/test_ext_math.py
index 296bba94f..82894974f 100644
--- a/tests/test_ext_math.py
+++ b/tests/test_ext_math.py
@@ -117,3 +117,26 @@ def test_math_number_all_latex(app, status, warning):
 
     macro = r'Referencing equation \\eqref{equation:math:foo}.'
     assert re.search(macro, content, re.S)
+
+
+@pytest.mark.sphinx('html', testroot='ext-math',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax'],
+                                   'math_eqref_format': 'Eq.{number}'})
+def test_math_eqref_format_html(app, status, warning):
+    app.builder.build_all()
+
+    content = (app.outdir / 'math.html').text()
+    html = ('<p>Referencing equation <a class="reference internal" '
+            'href="#equation-foo">Eq.1</a>.</p>')
+    assert html in content
+
+
+@pytest.mark.sphinx('latex', testroot='ext-math',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax'],
+                                   'math_eqref_format': 'Eq.{number}'})
+def test_math_eqref_format_latex(app, status, warning):
+    app.builder.build_all()
+
+    content = (app.outdir / 'test.tex').text()
+    macro = r'Referencing equation Eq.\\ref{equation:math:foo}.'
+    assert re.search(macro, content, re.S)