From 8e56f8638314e0a2332af886f825e6fd5598dc15 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 28 Jul 2018 19:54:56 +0900 Subject: [PATCH] Add :rst:role:`math:numref` role to refer equations (Same as :rst:role:`eq`) --- CHANGES | 1 + doc/usage/restructuredtext/domains.rst | 19 +++++++++++++++++++ doc/usage/restructuredtext/roles.rst | 8 +------- sphinx/builders/latex/transforms.py | 2 +- sphinx/domains/math.py | 8 ++++++-- tests/roots/test-ext-math/math.rst | 2 +- tests/test_ext_math.py | 10 +++++++--- 7 files changed, 36 insertions(+), 14 deletions(-) diff --git a/CHANGES b/CHANGES index b2bc9ead4..cdd6fa73d 100644 --- a/CHANGES +++ b/CHANGES @@ -186,6 +186,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 ---------- diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index c5b58c7d4..95d31f6ce 100644 --- a/doc/usage/restructuredtext/domains.rst +++ b/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 ------------ diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst index 6e819aa68..637df711b 100644 --- a/doc/usage/restructuredtext/roles.rst +++ b/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 diff --git a/sphinx/builders/latex/transforms.py b/sphinx/builders/latex/transforms.py index e3cfb2121..160c8c324 100644 --- a/sphinx/builders/latex/transforms.py +++ b/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']) diff --git a/sphinx/domains/math.py b/sphinx/domains/math.py index 78de09032..c88481746 100644 --- a/sphinx/domains/math.py +++ b/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? diff --git a/tests/roots/test-ext-math/math.rst b/tests/roots/test-ext-math/math.rst index 5a209bed4..c05c3a053 100644 --- a/tests/roots/test-ext-math/math.rst +++ b/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`. diff --git a/tests/test_ext_math.py b/tests/test_ext_math.py index 99940977b..d949c39a6 100644 --- a/tests/test_ext_math.py +++ b/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 = ('

Referencing equation Eq.1 and Eq.1.

') 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): '(1.2)') assert html in content html = ('

Referencing equation (1.1).

') + 'href="#equation-foo">(1.1) and ' + '(1.1).

') assert html in content @@ -205,7 +208,8 @@ def test_jsmath_numfig_html(app, status, warning): html = '(1.2)Referencing equation (1.1).

') + 'href="#equation-foo">(1.1) and ' + '(1.1).

') assert html in content