Merge pull request #5250 from tk0miya/refactor_math4

Add :rst:role:`math:numref` role to refer equations (Same as :rst:role:`eq`)

CHANGES

@@ -185,6 +185,7 @@ Features added
 * Apply :confval:`trim_doctest_flags` to all builders (cf. text, manpages)
 * #5140: linkcheck: Add better Accept header to HTTP client
 * #4614: sphinx-build: Add ``--keep-going`` option to show all warnings
+* Add :rst:role:`math:numref` role to refer equations (Same as :rst:role:`eq`)
 
 Bugs fixed
 ----------

doc/usage/restructuredtext/domains.rst

@@ -1325,6 +1325,25 @@ These roles are provided to refer to the described objects:
 .. rst:role:: rst:dir
               rst:role
 
+.. _math-domain:
+
+The Math Domain
+---------------
+
+The math domain (name **math**) provides the following roles::
+
+.. rst:role:: math:numref
+
+   Role for cross-referencing equations defined by :rst:dir:`math` directive
+   via their label.  Example::
+
+      .. math:: e^{i\pi} + 1 = 0
+         :label: euler
+
+      Euler's identity, equation :math:numref:`euler`, was elected one of the
+      most beautiful mathematical formulas.
+
+   .. versionadded:: 1.8
 
 More domains
 ------------

doc/usage/restructuredtext/roles.rst

@@ -288,13 +288,7 @@ Math
 
 .. rst:role:: eq
 
-   Role for cross-referencing equations via their label.  Example::
-
-      .. math:: e^{i\pi} + 1 = 0
-         :label: euler
-
-      Euler's identity, equation :eq:`euler`, was elected one of the most
-      beautiful mathematical formulas.
+   Same as :rst:role:`math:numref`.
 
 
 Other semantic markup

sphinx/builders/latex/transforms.py

@@ -561,7 +561,7 @@ class MathReferenceTransform(SphinxTransform):
 
         equations = self.env.get_domain('math').data['objects']
         for node in self.document.traverse(addnodes.pending_xref):
-            if node['refdomain'] == 'math' and node['reftype'] == 'eq':
+            if node['refdomain'] == 'math' and node['reftype'] in ('eq', 'numref'):
                 docname, _ = equations.get(node['reftarget'], (None, None))
                 if docname:
                     refnode = math_reference('', docname=docname, target=node['reftarget'])

sphinx/domains/math.py

@@ -21,10 +21,11 @@ from sphinx.util.nodes import make_refnode
 
 if False:
     # For type annotation
-    from typing import Any, Callable, Dict, Iterable, List, Tuple  # NOQA
+    from typing import Any, Callable, Dict, Iterable, List, Tuple, Union  # NOQA
     from sphinx.application import Sphinx  # NOQA
     from sphinx.builders import Builder  # NOQA
     from sphinx.environment import BuildEnvironment  # NOQA
+    from sphinx.util.typing import RoleFunction  # NOQA
 
 logger = logging.getLogger(__name__)
 
@@ -51,6 +52,9 @@ class MathDomain(Domain):
         displaymath: ('displaymath', None),
         nodes.math_block: ('displaymath', None),
     }  # type: Dict[nodes.Node, Tuple[unicode, Callable]]
+    roles = {
+        'numref': MathReferenceRole(),
+    }
 
     def clear_doc(self, docname):
         # type: (unicode) -> None
@@ -66,7 +70,7 @@ class MathDomain(Domain):
 
     def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
         # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node  # NOQA
-        assert typ == 'eq'
+        assert typ in ('eq', 'numref')
         docname, number = self.data['objects'].get(target, (None, None))
         if docname:
             # TODO: perhaps use rather a sphinx-core provided prefix here?

tests/roots/test-ext-math/math.rst

@@ -28,4 +28,4 @@ This is inline math: :math:`a^2 + b^2 = c^2`.
 
    a + 1 < b
 
-Referencing equation :eq:`foo`.
+Referencing equation :eq:`foo` and :math:numref:`foo`.

tests/test_ext_math.py

@@ -162,6 +162,7 @@ def test_math_eqref_format_html(app, status, warning):
 
     content = (app.outdir / 'math.html').text()
     html = ('<p>Referencing equation <a class="reference internal" '
+            'href="#equation-foo">Eq.1</a> and <a class="reference internal" '
             'href="#equation-foo">Eq.1</a>.</p>')
     assert html in content
 
@@ -173,7 +174,8 @@ 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}.'
+    macro = (r'Referencing equation Eq.\\ref{equation:math:foo} and '
+             r'Eq.\\ref{equation:math:foo}.')
     assert re.search(macro, content, re.S)
 
 
@@ -189,7 +191,8 @@ def test_mathjax_numfig_html(app, status, warning):
             '<span class="eqno">(1.2)')
     assert html in content
     html = ('<p>Referencing equation <a class="reference internal" '
-            'href="#equation-foo">(1.1)</a>.</p>')
+            'href="#equation-foo">(1.1)</a> and '
+            '<a class="reference internal" href="#equation-foo">(1.1)</a>.</p>')
     assert html in content
 
 
@@ -205,7 +208,8 @@ def test_jsmath_numfig_html(app, status, warning):
     html = '<span class="eqno">(1.2)<a class="headerlink" href="#equation-math-0"'
     assert html in content
     html = ('<p>Referencing equation <a class="reference internal" '
-            'href="#equation-foo">(1.1)</a>.</p>')
+            'href="#equation-foo">(1.1)</a> and '
+            '<a class="reference internal" href="#equation-foo">(1.1)</a>.</p>')
     assert html in content