From a4c7be6fcdf6d6fcef8d781707a86a7eb8216bb5 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Tue, 15 May 2018 23:21:01 +0900 Subject: [PATCH] Move MathDomain to sphinx.domains.math --- CHANGES | 1 + doc/extdev/index.rst | 5 ++ sphinx/application.py | 1 + sphinx/domains/math.py | 130 +++++++++++++++++++++++++++++++++++++++++ sphinx/ext/mathbase.py | 98 +------------------------------ 5 files changed, 139 insertions(+), 96 deletions(-) create mode 100644 sphinx/domains/math.py diff --git a/CHANGES b/CHANGES index a55bc2fff..cd00e52d6 100644 --- a/CHANGES +++ b/CHANGES @@ -75,6 +75,7 @@ Deprecated * ``sphinx.ext.mathbase.math`` node is deprecated * ``sphinx.ext.mathbase.displaymath`` node is deprecated * ``sphinx.ext.mathbase.is_in_section_title()`` is deprecated +* ``sphinx.ext.mathbase.MathDomain`` is deprecated For more details, see `deprecation APIs list `_ diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 17effd7bd..c48f93012 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -126,6 +126,11 @@ The following is a list of deprecated interface. - 4.0 - :meth:`~sphinx.application.Sphinx.add_css_file()` + * - ``sphinx.ext.mathbase.MathDomain`` + - 1.8 + - 3.0 + - ``sphinx.domains.math.MathDomain`` + * - ``sphinx.ext.mathbase.is_in_section_title()`` - 1.8 - 3.0 diff --git a/sphinx/application.py b/sphinx/application.py index f36135cf8..782415e89 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -83,6 +83,7 @@ builtin_extensions = ( 'sphinx.domains.c', 'sphinx.domains.cpp', 'sphinx.domains.javascript', + 'sphinx.domains.math', 'sphinx.domains.python', 'sphinx.domains.rst', 'sphinx.domains.std', diff --git a/sphinx/domains/math.py b/sphinx/domains/math.py new file mode 100644 index 000000000..4230eb7a9 --- /dev/null +++ b/sphinx/domains/math.py @@ -0,0 +1,130 @@ +# -*- coding: utf-8 -*- +""" + sphinx.domains.math + ~~~~~~~~~~~~~~~~~~~ + + The math domain. + + :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +from docutils import nodes +from docutils.nodes import make_id + +from sphinx.addnodes import math_block as displaymath +from sphinx.domains import Domain +from sphinx.ext.mathbase import eqref +from sphinx.locale import __ +from sphinx.util import logging +from sphinx.util.nodes import make_refnode + +if False: + # For type annotation + from typing import Any, Callable, Dict, Iterable, List, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA + +logger = logging.getLogger(__name__) + + +class MathDomain(Domain): + """Mathematics domain.""" + name = 'math' + label = 'mathematics' + + initial_data = { + 'objects': {}, # labelid -> (docname, eqno) + } # type: Dict[unicode, Dict[unicode, Tuple[unicode, int]]] + dangling_warnings = { + 'eq': 'equation not found: %(target)s', + } + enumerable_nodes = { # node_class -> (figtype, title_getter) + displaymath: ('displaymath', None), + nodes.math_block: ('displaymath', None), + } # type: Dict[nodes.Node, Tuple[unicode, Callable]] + + def clear_doc(self, docname): + # type: (unicode) -> None + for equation_id, (doc, eqno) in list(self.data['objects'].items()): + if doc == docname: + del self.data['objects'][equation_id] + + def merge_domaindata(self, docnames, otherdata): + # type: (Iterable[unicode], Dict) -> None + for labelid, (doc, eqno) in otherdata['objects'].items(): + if doc in docnames: + self.data['objects'][labelid] = (doc, eqno) + + 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' + docname, number = self.data['objects'].get(target, (None, None)) + if docname: + if builder.name == 'latex': + newnode = eqref('', **node.attributes) + newnode['docname'] = docname + newnode['target'] = target + return newnode + else: + # TODO: perhaps use rather a sphinx-core provided prefix here? + node_id = make_id('equation-%s' % target) + if env.config.math_numfig and env.config.numfig: + if docname in env.toc_fignumbers: + number = env.toc_fignumbers[docname]['displaymath'].get(node_id, ()) + number = '.'.join(map(str, number)) + else: + 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) + title = nodes.Text("(%d)" % number) + return make_refnode(builder, fromdocname, docname, node_id, title) + else: + return None + + def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, nodes.Node, nodes.Node) -> List[nodes.Node] # NOQA + refnode = self.resolve_xref(env, fromdocname, builder, 'eq', target, node, contnode) + if refnode is None: + return [] + else: + return [refnode] + + def get_objects(self): + # type: () -> List + return [] + + def add_equation(self, env, docname, labelid): + # type: (BuildEnvironment, unicode, unicode) -> int + equations = self.data['objects'] + if labelid in equations: + path = env.doc2path(equations[labelid][0]) + msg = __('duplicate label of equation %s, other instance in %s') % (labelid, path) + raise UserWarning(msg) + else: + eqno = self.get_next_equation_number(docname) + equations[labelid] = (docname, eqno) + return eqno + + def get_next_equation_number(self, docname): + # type: (unicode) -> int + targets = [eq for eq in self.data['objects'].values() if eq[0] == docname] + return len(targets) + 1 + + +def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] + app.add_domain(MathDomain) + + return { + 'version': 'builtin', + 'env_version': 1, + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/sphinx/ext/mathbase.py b/sphinx/ext/mathbase.py index 89c6e9286..86c810341 100644 --- a/sphinx/ext/mathbase.py +++ b/sphinx/ext/mathbase.py @@ -12,24 +12,20 @@ import warnings from docutils import nodes -from docutils.nodes import make_id from sphinx.addnodes import math, math_block as displaymath from sphinx.config import string_classes from sphinx.deprecation import RemovedInSphinx30Warning -from sphinx.domains import Domain +from sphinx.domains.math import MathDomain # NOQA # to keep compatibility from sphinx.locale import __ from sphinx.roles import XRefRole from sphinx.util import logging -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, List, Tuple # NOQA from docutils.writers.html4css1 import Writer # NOQA from sphinx.application import Sphinx # NOQA - from sphinx.builders import Builder # NOQA - from sphinx.environment import BuildEnvironment # NOQA logger = logging.getLogger(__name__) @@ -45,95 +41,6 @@ class EqXRefRole(XRefRole): return [node], [] -class MathDomain(Domain): - """Mathematics domain.""" - name = 'math' - label = 'mathematics' - - initial_data = { - 'objects': {}, # labelid -> (docname, eqno) - } # type: Dict[unicode, Dict[unicode, Tuple[unicode, int]]] - dangling_warnings = { - 'eq': 'equation not found: %(target)s', - } - enumerable_nodes = { # node_class -> (figtype, title_getter) - displaymath: ('displaymath', None), - nodes.math_block: ('displaymath', None), - } # type: Dict[nodes.Node, Tuple[unicode, Callable]] - - def clear_doc(self, docname): - # type: (unicode) -> None - for equation_id, (doc, eqno) in list(self.data['objects'].items()): - if doc == docname: - del self.data['objects'][equation_id] - - def merge_domaindata(self, docnames, otherdata): - # type: (Iterable[unicode], Dict) -> None - for labelid, (doc, eqno) in otherdata['objects'].items(): - if doc in docnames: - self.data['objects'][labelid] = (doc, eqno) - - 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' - docname, number = self.data['objects'].get(target, (None, None)) - if docname: - if builder.name == 'latex': - newnode = eqref('', **node.attributes) - newnode['docname'] = docname - newnode['target'] = target - return newnode - else: - # TODO: perhaps use rather a sphinx-core provided prefix here? - node_id = make_id('equation-%s' % target) - if env.config.math_numfig and env.config.numfig: - if docname in env.toc_fignumbers: - number = env.toc_fignumbers[docname]['displaymath'].get(node_id, ()) - number = '.'.join(map(str, number)) - else: - 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) - title = nodes.Text("(%d)" % number) - return make_refnode(builder, fromdocname, docname, node_id, title) - else: - return None - - def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode): - # type: (BuildEnvironment, unicode, Builder, unicode, nodes.Node, nodes.Node) -> List[nodes.Node] # NOQA - refnode = self.resolve_xref(env, fromdocname, builder, 'eq', target, node, contnode) - if refnode is None: - return [] - else: - return [refnode] - - def get_objects(self): - # type: () -> List - return [] - - def add_equation(self, env, docname, labelid): - # type: (BuildEnvironment, unicode, unicode) -> int - equations = self.data['objects'] - if labelid in equations: - path = env.doc2path(equations[labelid][0]) - msg = __('duplicate label of equation %s, other instance in %s') % (labelid, path) - raise UserWarning(msg) - else: - eqno = self.get_next_equation_number(docname) - equations[labelid] = (docname, eqno) - return eqno - - def get_next_equation_number(self, docname): - # type: (unicode) -> int - targets = [eq for eq in self.data['objects'].values() if eq[0] == docname] - return len(targets) + 1 - - def get_node_equation_number(writer, node): # type: (Writer, nodes.Node) -> unicode if writer.builder.config.math_numfig and writer.builder.config.numfig: @@ -225,7 +132,6 @@ def setup_math(app, htmlinlinevisitors, htmldisplayvisitors): # type: (Sphinx, Tuple[Callable, Any], Tuple[Callable, Any]) -> None app.add_config_value('math_eqref_format', None, 'env', string_classes) app.add_config_value('math_numfig', True, 'env') - app.add_domain(MathDomain) app.add_node(math, override=True, html=htmlinlinevisitors) app.add_node(displaymath, override=True,