Math support for HTML outputs in Sphinx
***************************************

New in version 0.5.

Changed in version 1.8: Math support for non-HTML builders is
integrated to sphinx-core. So mathbase extension is no longer needed.

Since mathematical notation isn't natively supported by HTML in any
way, Sphinx gives a math support to HTML document with several
extensions.  These use the reStructuredText math "directive" and
"role".


"sphinx.ext.imgmath" -- Render math as images
=============================================

New in version 1.4.

This extension renders math via LaTeX and dvipng or dvisvgm into PNG
or SVG images. This of course means that the computer where the docs
are built must have both programs available.

There are various configuration values you can set to influence how
the images are built:

imgmath_image_format

   The output image format. The default is "'png'". It should be
   either "'png'" or "'svg'". The image is produced by first executing
   "latex" on the TeX mathematical mark-up then (depending on the
   requested format) either dvipng or dvisvgm.

imgmath_use_preview

   "dvipng" and "dvisvgm" both have the ability to collect from LaTeX
   the "depth" of the rendered math: an inline image should use this
   "depth" in a "vertical-align" style to get correctly aligned with
   surrounding text.

   This mechanism requires the LaTeX preview package (available as
   "preview-latex-style" on Ubuntu xenial).  Therefore, the default
   for this option is "False" but it is strongly recommended to set it
   to "True".

   Changed in version 2.2: This option can be used with the "'svg'"
   "imgmath_image_format".

imgmath_add_tooltips

   Default: "True".  If false, do not add the LaTeX code as an "alt"
   attribute for math images.

imgmath_font_size

   The font size (in "pt") of the displayed math.  The default value
   is "12".  It must be a positive integer.

imgmath_latex

   The command name with which to invoke LaTeX.  The default is
   "'latex'"; you may need to set this to a full path if "latex" is
   not in the executable search path.

   Since this setting is not portable from system to system, it is
   normally not useful to set it in "conf.py"; rather, giving it on
   the **sphinx-build** command line via the "-D" option should be
   preferable, like this:

      sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html

   This value should only contain the path to the latex executable,
   not further arguments; use "imgmath_latex_args" for that purpose.

   Hint:

     Some fancy LaTeX mark-up (an example was reported which used TikZ
     to add various decorations to the equation) require multiple runs
     of the LaTeX executable.  To handle this, set this configuration
     setting to "'latexmk'" (or a full path to it) as this Perl script
     reliably chooses dynamically how many latex runs are needed.

imgmath_latex_args

   Additional arguments to give to latex, as a list.  The default is
   an empty list.

imgmath_latex_preamble

   Additional LaTeX code to put into the preamble of the LaTeX files
   used to translate the math snippets.  This is left empty by
   default.  Use it e.g. to add packages which modify the fonts used
   for math, such as "'\\usepackage{newtxsf}'" for sans-serif fonts,
   or "'\\usepackage{fouriernc}'" for serif fonts.  Indeed, the
   default LaTeX math fonts have rather thin glyphs which (in HTML
   output) often do not match well with the font for text.

imgmath_dvipng

   The command name to invoke "dvipng".  The default is "'dvipng'";
   you may need to set this to a full path if "dvipng" is not in the
   executable search path. This option is only used when
   "imgmath_image_format" is set to "'png'".

imgmath_dvipng_args

   Additional arguments to give to dvipng, as a list.  The default
   value is "['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']"
   which makes the image a bit darker and larger then it is by default
   (this compensates somewhat for the thinness of default LaTeX math
   fonts), and produces PNGs with a transparent background.  This
   option is used only when "imgmath_image_format" is "'png'".

imgmath_dvisvgm

   The command name to invoke "dvisvgm".  The default is "'dvisvgm'";
   you may need to set this to a full path if "dvisvgm" is not in the
   executable search path.  This option is only used when
   "imgmath_image_format" is "'svg'".

imgmath_dvisvgm_args

   Additional arguments to give to dvisvgm, as a list. The default
   value is "['--no-fonts']", which means that "dvisvgm" will render
   glyphs as path elements (cf the dvisvgm FAQ). This option is used
   only when "imgmath_image_format" is "'svg'".


"sphinx.ext.mathjax" -- Render math via JavaScript
==================================================

New in version 1.1.

This extension puts math as-is into the HTML files.  The JavaScript
package MathJax is then loaded and transforms the LaTeX markup to
readable math live in the browser.

Because MathJax (and the necessary fonts) is very large, it is not
included in Sphinx but is set to automatically include it from a
third-party site.

Attention:

  You should use the math "directive" and "role", not the native
  MathJax "$$", "\(", etc.

mathjax_path

   The path to the JavaScript file to include in the HTML files in
   order to load MathJax.

   The default is the "https://" URL that loads the JS files from the
   cdnjs Content Delivery Network. See the MathJax Getting Started
   page for details. If you want MathJax to be available offline or
   without including resources from a third-party site, you have to
   download it and set this value to a different path.

   The path can be absolute or relative; if it is relative, it is
   relative to the "_static" directory of the built docs.

   For example, if you put MathJax into the static path of the Sphinx
   docs, this value would be "MathJax/MathJax.js".  If you host more
   than one Sphinx documentation set on one server, it is advisable to
   install MathJax in a shared location.

   You can also give a full "https://" URL different from the CDN URL.

mathjax_options

   The options to script tag for mathjax.  For example, you can set
   integrity option with following setting:

      mathjax_options = {
          'integrity': 'sha384-......',
      }

   The default is empty ("{}").

mathjax_config

   The inline configuration options for mathjax.  The value is used as
   a parameter of "MathJax.Hub.Config()".  For more information,
   please read Using in-line configuration options.

   For example:

      mathjax_config = {
          'extensions': ['tex2jax.js'],
          'jax': ['input/TeX', 'output/HTML-CSS'],
      }

   The default is empty (not configured).


"sphinx.ext.jsmath" -- Render math via JavaScript
=================================================

This extension works just as the MathJax extension does, but uses the
older package jsMath.  It provides this config value:

jsmath_path

   The path to the JavaScript file to include in the HTML files in
   order to load JSMath.  There is no default.

   The path can be absolute or relative; if it is relative, it is
   relative to the "_static" directory of the built docs.

   For example, if you put JSMath into the static path of the Sphinx
   docs, this value would be "jsMath/easy/load.js".  If you host more
   than one Sphinx documentation set on one server, it is advisable to
   install jsMath in a shared location.
