source: sasview/docs/sphinx-docs/source/_extensions/mathjax.py @ 33d3a74

# -*- coding: utf-8 -*-
"""
    sphinx.ext.mathjax
    ~~~~~~~~~~~~~~~~~~

    Allow `MathJax <http://mathjax.org/>`_ to be used to display math in
    Sphinx's HTML writer -- requires the MathJax JavaScript library on your
    webserver/computer.

    :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.

    sample lines in conf.py to use this::

        mathjax_path = ['https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.6.0/katex.min.js',
                        'http://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.6.0/contrib/auto-render.min.js',
                        'rendermath.js']
        mathjax_css = 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.6.0/katex.min.css'

    with rendermath.js containing::

        document.addEventListener("DOMContentLoaded", function(event) {
            renderMathInElement(document.body);
        });

    2016-08-09 Jason Sachs
    * allow list of URLS for mathjax_path, which permits use of katex.js
"""

from docutils import nodes

import sphinx
from sphinx.locale import _
from sphinx.errors import ExtensionError
from sphinx.ext.mathbase import setup_math as mathbase_setup


def html_visit_math(self, node):
    self.body.append(self.starttag(node, 'span', '', CLASS='math'))
    self.body.append(self.builder.config.mathjax_inline[0] +
                     self.encode(node['latex']) +
                     self.builder.config.mathjax_inline[1] + '</span>')
    raise nodes.SkipNode


def html_visit_displaymath(self, node):
    self.body.append(self.starttag(node, 'div', CLASS='math'))
    if node['nowrap']:
        self.body.append(self.encode(node['latex']))
        self.body.append('</div>')
        raise nodes.SkipNode

    # necessary to e.g. set the id property correctly
    if node['number']:
        self.body.append('<span class="eqno">(%s)' % node['number'])
        self.add_permalink_ref(node, _('Permalink to this equation'))
        self.body.append('</span>')
    self.body.append(self.builder.config.mathjax_display[0])
    parts = [prt for prt in node['latex'].split('\n\n') if prt.strip()]
    if len(parts) > 1:  # Add alignment if there are more than 1 equation
        self.body.append(r' \begin{align}\begin{aligned}')
    for i, part in enumerate(parts):
        part = self.encode(part)
        if r'\\' in part:
            self.body.append(r'\begin{split}' + part + r'\end{split}')
        else:
            self.body.append(part)
        if i < len(parts) - 1:  # append new line if not the last equation
            self.body.append(r'\\')
    if len(parts) > 1:  # Add alignment if there are more than 1 equation
        self.body.append(r'\end{aligned}\end{align} ')
    self.body.append(self.builder.config.mathjax_display[1])
    self.body.append('</div>\n')
    raise nodes.SkipNode

try:
    basestring
except:
    basestring = str

def builder_inited(app):
    jaxpath = app.config.mathjax_path
    if not jaxpath:
        raise ExtensionError('mathjax_path config value must be set for the '
                             'mathjax extension to work')

    # app.config.mathjax_path can be a string or a list of strings
    if isinstance(jaxpath, basestring):
        app.add_javascript(jaxpath)
    else:
        for p in jaxpath:
            app.add_javascript(p)

    if app.config.mathjax_css:
        app.add_stylesheet(app.config.mathjax_css)


def setup(app):
    try:
        mathbase_setup(app, (html_visit_math, None), (html_visit_displaymath, None))
    except ExtensionError:
        raise ExtensionError('sphinx.ext.mathjax: other math package is already loaded')

    # more information for mathjax secure url is here:
    # http://docs.mathjax.org/en/latest/start.html#secure-access-to-the-cdn
    app.add_config_value('mathjax_path',
                         'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?'
                         'config=TeX-MML-AM_CHTML',
                         #'config=TeX-AMS-MML_HTMLorMML',
                         False)
    app.add_config_value('mathjax_css', None, 'html')
    app.add_config_value('mathjax_use_katex', False, 'html')
    app.add_config_value('mathjax_inline', [r'\(', r'\)'], 'html')
    app.add_config_value('mathjax_display', [r'\[', r'\]'], 'html')
    app.connect('builder-inited', builder_inited)

    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}