Merge pull request #3676 from tk0miya/3638_eqref_format

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

CHANGES

@@ -10,9 +10,11 @@ Deprecated
 Features added
 --------------
 
-- C++, handle ``decltype(auto)``.
-- #2406: C++, add proper parsing of expressions, including linking of identifiers.
-- C++, add a ``cpp:expr`` role for inserting inline C++ expressions or types.
+* C++, handle ``decltype(auto)``.
+* #2406: C++, add proper parsing of expressions, including linking of identifiers.
+* C++, add a ``cpp:expr`` role for inserting inline C++ expressions or types.
+* #3638: Allow to change a label of reference to equation using
+  ``math_eqref_format``
 
 Features removed
 ----------------

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

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

tests/test_ext_math.py

@@ -116,3 +116,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)