DOC: switch to KaTeX for math rendering

Author: hagenw

doc/conf.py

@@ -17,6 +17,11 @@
 import os
 from subprocess import check_output
 
+import sphinxcontrib.katex as katex
+
+sys.path.insert(0, os.path.abspath('.'))
+from math_definitions import latex_macros
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -32,7 +37,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.mathjax',
+    'sphinxcontrib.katex',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',  # support for NumPy-style docstrings
     'sphinx.ext.intersphinx',
@@ -149,6 +154,10 @@
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
+# Math settings
+katex_macros = katex.latex_defs_to_katex_macros(latex_macros)
+katex_options = 'macros: {' + katex_macros + '}'
+
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -251,7 +260,7 @@ def setup(app):
 #'pointsize': '10pt',
 
 # Additional stuff for the LaTeX preamble.
-#'preamble': '',
+'preamble': latex_macros,
 
 'printindex': '',
 }

doc/math-definitions.rst

@@ -0,0 +1,10 @@
+latex_macros = r"""
+    \def \dirac      #1{\operatorname{\delta}\left(#1\right)}
+    \def \e          #1{\operatorname{e}^{#1}}
+    \def \Hankel     #3{\mathop{{}H_{#2}^{(#1)}}\!\left(#3\right)}
+    \def \hankel     #3{\mathop{{}h_{#2}^{(#1)}}\!\left(#3\right)}
+    \def \i            {\mathrm{i}}
+    \def \scalarprod #2{\left\langle#1,#2\right\rangle}
+    \def \vec        #1{\mathbf{#1}}
+    \def \wc           {\frac{\omega}{c}}
+"""

doc/math_definitions.py

@@ -12,3 +12,4 @@ dependencies:
   - pandoc
   - pip:
     - nbsphinx
+    - sphinxcontrib-katex

doc/readthedocs-environment.yml

@@ -3,6 +3,7 @@ Sphinx-RTD-Theme
 nbsphinx
 ipykernel
 sphinxcontrib-bibtex
+sphinxcontrib-katex
 
 NumPy
 SciPy

doc/requirements.txt

@@ -1,9 +1,4 @@
-"""Compute driving functions for various systems.
-
-.. include:: math-definitions.rst
-
-"""
-
+"""Compute driving functions for various systems."""
 import numpy as np
 from numpy.core.umath_tests import inner1d  # element-wise inner product
 from scipy.special import jn, hankel2

sfs/mono/drivingfunction.py

@@ -1,8 +1,4 @@
-"""Compute time based driving functions for various systems.
-
-.. include:: math-definitions.rst
-
-"""
+"""Compute time based driving functions for various systems."""
 import numpy as np
 from numpy.core.umath_tests import inner1d  # element-wise inner product
 from .. import defs

sfs/time/drivingfunction.py

@@ -2,8 +2,6 @@
 
 The Green's function describes the spatial sound propagation over time.
 
-.. include:: math-definitions.rst
-
 """
 
 import numpy as np

sfs/time/source.py

@@ -1,9 +1,4 @@
-"""Various utility functions.
-
-.. include:: math-definitions.rst
-
-"""
-
+"""Various utility functions."""
 import collections
 import numpy as np
 from scipy.special import spherical_jn, spherical_yn