diff options
| -rw-r--r-- | CHANGES | 3 | ||||
| -rw-r--r-- | doc/ext/math.rst | 7 | ||||
| -rw-r--r-- | sphinx/ext/mathbase.py | 25 | ||||
| -rw-r--r-- | tests/test_ext_math.py | 23 |
4 files changed, 56 insertions, 2 deletions
@@ -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) |