Extend the HTML and LaTeX translator

Instead of overwriting the nodes, we extend the translators provided by
Sphinx, and customize the visit_math and visit_math_block logic, to do
our hyperlinking logic before calling the base class visit methods. This
allows us to deduplicate the logic we copied earlier.

For mathdefbs.py, remove all latex related logic, since we don't use
this extension to build latex.

Issue #1157

Author: ngzhian

document/core/util/mathdef.py

@@ -1,12 +1,10 @@
 from sphinx.ext.mathbase import math
-from sphinx.ext.mathbase import displaymath
 from sphinx.ext.mathbase import MathDirective
-from sphinx.ext.mathjax import html_visit_math
-from sphinx.ext.mathjax import html_visit_displaymath
-from sphinx.util.texescape import tex_escape_map, tex_replace_map
-from docutils import nodes, utils
+from sphinx.util.texescape import tex_replace_map
+from sphinx.writers.html5 import HTML5Translator
+from sphinx.writers.latex import LaTeXTranslator
+from docutils import nodes
 from docutils.parsers.rst.directives.misc import Replace
-from docutils.parsers.rst.roles import math_role
 from six import text_type
 import re
 
@@ -22,14 +20,6 @@ def html_transform_math_xref(node):
   new_text = xref_re.sub(lambda m: html_hyperlink(m.group(1), m.group(2)), node.astext())
   node.children[0] = nodes.Text(new_text)
 
-def ext_html_visit_math(self, node):
-  html_transform_math_xref(node)
-  html_visit_math(self, node)
-
-def ext_html_visit_displaymath(self, node):
-  html_transform_math_xref(node)
-  html_visit_displaymath(self, node)
-
 # Mirrors sphinx/writers/latex
 def latex_hyperlink(file, id):
   id = text_type(id).translate(tex_replace_map).\
@@ -41,42 +31,6 @@ def latex_transform_math_xref(node):
   new_text = xref_re.sub(lambda m: latex_hyperlink(m.group(1), m.group(2)), node.astext())
   node.children[0] = nodes.Text(new_text)
 
-# TODO: this is duplicated from sphinx.writers.latex.LaTeXTranslator, figure out
-# a better way to extend it so that we don't have to duplicate this code.
-def latex_visit_math(self, node):
-  if self.in_title:
-      self.body.append(r'\protect\(%s\protect\)' % node.astext())
-  else:
-      self.body.append(r'\(%s\)' % node.astext())
-  raise nodes.SkipNode
-
-def ext_latex_visit_math(self, node):
-  latex_transform_math_xref(node)
-  latex_visit_math(self, node)
-
-# TODO: this is duplicated from sphinx.writers.latex.LaTeXTranslator, figure out
-# a better way to extend it so that we don't have to duplicate this code.
-def latex_visit_displaymath(self, node):
-  if node.get('label'):
-      label = "equation:%s:%s" % (node['docname'], node['label'])
-  else:
-      label = None
-
-  if node.get('nowrap'):
-      if label:
-          self.body.append(r'\label{%s}' % label)
-      self.body.append(node.astext())
-  else:
-      from sphinx.util.math import wrap_displaymath
-      self.body.append(wrap_displaymath(node.astext(), label,
-                                        self.builder.config.math_number_all))
-  raise nodes.SkipNode
-
-def ext_latex_visit_displaymath(self, node):
-  latex_transform_math_xref(node)
-  latex_visit_displaymath(self, node)
-
-
 # Expand mathdef names in math roles and directives
 
 def_re = re.compile('\\\\[A-Za-z][0-9A-Za-z]*', re.M)
@@ -110,7 +64,7 @@ def run(self):
       self.content[i] = replace_mathdefs(doc, s)
     for i, s in enumerate(self.arguments):
       self.arguments[i] = replace_mathdefs(doc, s)
-    return super(ExtMathDirective, self).run()
+    return super().run()
 
 class MathdefDirective(Replace):
   def run(self):
@@ -130,20 +84,39 @@ def run(self):
     doc.mathdefs[name] = [arity, ''.join(self.content)]
     self.content[0] = ':math:`' + self.content[0]
     self.content[-1] = self.content[-1] + '`'
-    return super(MathdefDirective, self).run()
-
+    return super().run()
+
+class WebAssemblyHTML5Translator(HTML5Translator):
+  """
+  Customize HTML5Translator.
+  Convert xref in math and math block nodes to hrefs.
+  """
+  def visit_math(self, node, math_env = ''):
+    html_transform_math_xref(node)
+    super().visit_math(node, math_env)
+
+  def visit_math_block(self, node, math_env  = ''):
+    html_transform_math_xref(node)
+    super().visit_math_block(node, math_env)
+
+class WebAssemblyLaTeXTranslator(LaTeXTranslator):
+  """
+  Customize LaTeXTranslator.
+  Convert xref in math and math block nodes to hyperrefs.
+  """
+  def visit_math(self, node):
+    latex_transform_math_xref(node)
+    super().visit_math(node)
+
+  def visit_math_block(self, node):
+    latex_transform_math_xref(node)
+    super().visit_math_block(node)
 
 # Setup
 
 def setup(app):
-  app.add_node(math,
-               override = True,
-               html = (ext_html_visit_math, None),
-               latex = (ext_latex_visit_math, None))
-  app.add_node(displaymath,
-               override = True,
-               html = (ext_html_visit_displaymath, None),
-               latex = (ext_latex_visit_displaymath, None))
+  app.set_translator('html', WebAssemblyHTML5Translator)
+  app.set_translator('latex', WebAssemblyLaTeXTranslator)
   app.add_role('math', ext_math_role)
-  app.add_directive('math', ExtMathDirective)
+  app.add_directive('math', ExtMathDirective, override = True)
   app.add_directive('mathdef', MathdefDirective)

document/core/util/mathdefbs.py

@@ -4,15 +4,12 @@
 # mathdef.py controlled by buildername.
 
 from sphinx.ext.mathbase import math
-from sphinx.ext.mathbase import displaymath
 from sphinx.ext.mathbase import MathDirective
 from sphinx.ext.mathjax import html_visit_math
 from sphinx.ext.mathjax import html_visit_displaymath
-from sphinx.util.texescape import tex_escape_map, tex_replace_map
-from docutils import nodes, utils
+from sphinx.writers.html5 import HTML5Translator
+from docutils import nodes
 from docutils.parsers.rst.directives.misc import Replace
-from docutils.parsers.rst.roles import math_role
-from six import text_type
 import re
 
 
@@ -27,57 +24,6 @@ def html_transform_math_xref(node):
   new_text = xref_re.sub(lambda m: html_hyperlink(m.group(1), m.group(2)), node.astext())
   node.children[0] = nodes.Text(new_text)
 
-def ext_html_visit_math(self, node):
-  html_transform_math_xref(node)
-  html_visit_math(self, node)
-
-def ext_html_visit_displaymath(self, node):
-  html_transform_math_xref(node)
-  html_visit_displaymath(self, node)
-
-# Mirrors sphinx/writers/latex
-def latex_hyperlink(file, id):
-  id = text_type(id).translate(tex_replace_map).\
-    encode('ascii', 'backslashreplace').decode('ascii').\
-    replace('_', '-').replace('\\', '_')
-  return '\\hyperref[%s:%s]' % (file, id)
-
-def latex_transform_math_xref(node):
-  new_text = xref_re.sub(lambda m: latex_hyperlink(m.group(1), m.group(2)), node.astext())
-  node.children[0] = nodes.Text(new_text)
-
-def latex_visit_math(self, node):
-  if self.in_title:
-      self.body.append(r'\protect\(%s\protect\)' % node.astext())
-  else:
-      self.body.append(r'\(%s\)' % node.astext())
-  raise nodes.SkipNode
-
-def ext_latex_visit_math(self, node):
-  latex_transform_math_xref(node)
-  latex_visit_math(self, node)
-
-def latex_visit_displaymath(self, node):
-  if node.get('label'):
-      label = "equation:%s:%s" % (node['docname'], node['label'])
-  else:
-      label = None
-
-  if node.get('nowrap'):
-      if label:
-          self.body.append(r'\label{%s}' % label)
-      self.body.append(node.astext())
-  else:
-      from sphinx.util.math import wrap_displaymath
-      self.body.append(wrap_displaymath(node.astext(), label,
-                                        self.builder.config.math_number_all))
-  raise nodes.SkipNode
-
-def ext_latex_visit_displaymath(self, node):
-  latex_transform_math_xref(node)
-  latex_visit_displaymath(self, node)
-
-
 # Expand mathdef names in math roles and directives
 
 def_re = re.compile('\\\\[A-Za-z][0-9A-Za-z]*', re.M)
@@ -132,18 +78,23 @@ def run(self):
     self.content[-1] = self.content[-1] + '`'
     return super(MathdefDirective, self).run()
 
+class WebAssemblyHTML5Translator(HTML5Translator):
+  """
+  Customize HTML5Translator.
+  Convert xref in math and math block nodes to hrefs.
+  """
+  def visit_math(self, node, math_env = ''):
+    html_transform_math_xref(node)
+    super().visit_math(node, math_env)
+
+  def visit_math_block(self, node, math_env  = ''):
+    html_transform_math_xref(node)
+    super().visit_math_block(node, math_env)
 
 # Setup
 
 def setup(app):
-  app.add_node(math,
-               override = True,
-               html = (ext_html_visit_math, None),
-               latex = (ext_latex_visit_math, None))
-  app.add_node(displaymath,
-               override = True,
-               html = (ext_html_visit_displaymath, None),
-               latex = (ext_latex_visit_displaymath, None))
+  app.set_translator('singlehtml', WebAssemblyHTML5Translator)
   app.add_role('math', ext_math_role)
-  app.add_directive('math', ExtMathDirective)
+  app.add_directive('math', ExtMathDirective, override = True)
   app.add_directive('mathdef', MathdefDirective)