Add math support to Sphinx.

2 files changed, 185 insertions, 0 deletions

diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index 1cd045ae..551a9477 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -150,6 +150,14 @@ the following public API:
    Add the standard docutils :class:`Transform` subclass *transform* to the list
    of transforms that are applied after Sphinx parses a reST document.
 
+.. method:: Sphinx.add_javascript(filename)
+
+   Add *filename* to the list of JavaScript files that the default HTML template
+   will include.  The filename must be relative to the HTML static path, see
+   :confval:`the docs for the config value <html_static_path>`.
+
+   .. versionadded:: 0.5
+   
 .. method:: Sphinx.connect(event, callback)
 
    Register *callback* to be called when *event* is emitted.  For details on
@@ -254,6 +262,17 @@ registered event handlers.
 
    .. versionadded:: 0.4
 
+.. event:: build-finished (app, exception)
+
+   Emitted when a build has finished, before Sphinx exits, usually used for
+   cleanup.  This event is emitted even when the build process raised an
+   exception, given as the *exception* argument.  The exception is reraised in
+   the application after the event handlers have run.  If the build process
+   raised no exception, *exception* will be ``None``.  This allows to customize
+   cleanup actions depending on the exception status.
+
+   .. versionadded:: 0.5
+   
 
 .. _template-bridge:
 
diff --git a/doc/ext/math.rst b/doc/ext/math.rst
new file mode 100644
index 00000000..4c582035
--- /dev/null
+++ b/doc/ext/math.rst
@@ -0,0 +1,166 @@
+.. highlight:: rest
+
+Math support in Sphinx
+======================
+
+.. module:: sphinx.ext.mathbase
+   :synopsis: Common math support for pngmath and jsmath.
+
+.. versionadded:: 0.5
+
+Since mathematical notation isn't natively supported by HTML in any way, Sphinx
+supports math in documentation with two extensions.
+
+The basic math support that is common to both extensions is contained in
+:mod:`sphinx.ext.mathbase`.  Other math support extensions should, if possible,
+reuse that support too.
+
+The input language for mathematics is LaTeX markup.  This is the de-facto
+standard for plain-text math notation and has the added advantage that no
+further translation is necessary when building LaTeX output.
+
+:mod:`mathbase` defines these new markup elements:
+
+.. role:: math
+
+   Role for inline math.  Use like this::
+
+      Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
+
+.. directive:: math
+
+   Directive for displayed math (math that takes the whole line for itself).
+
+   The directive supports multiple equations, which should be separated by a
+   blank line::
+
+      .. math::
+
+         (a + b)^2 = a^2 + 2ab + b^2
+
+         (a - b)^2 = a^2 - 2ab + b^2
+
+   In addition, each single equation is set within a ``split`` environment,
+   which means that you can have multiple aligned lines in an equation,
+   aligned at ``&`` and separated by ``\\``::
+
+      .. math::
+
+         (a + b)^2  &=  (a + b)(a + b) \\
+                    &=  a^2 + 2ab + b^2
+
+   For more details, look into the documentation of the `AmSMath LaTeX
+   package`_.
+
+   When the math is only one line of text, it can also be given as a directive
+   argument::
+
+      .. math:: (a + b)^2 = a^2 + 2ab + b^2
+
+   Normally, equations are not numbered.  If you want your equation to get a
+   number, use the ``label`` option.  When given, it selects a label for the
+   equation, by which it can be cross-referenced, and causes an equation number
+   to be issued.  See :role:`eqref` for an example.  The numbering style depends
+   on the output format.
+
+.. role:: eqref
+
+   Role for cross-referencing equations via their label.  This currently works
+   only within the same document.  Example::
+
+      .. math:: e^{i\pi} + 1 = 0
+         :label: euler
+
+      Euler's identity, equation :eqref:`euler`, was elected one of the most
+      beautiful mathematical formulas.
+   
+
+:mod:`sphinx.ext.pngmath` -- Render math as PNG images
+------------------------------------------------------
+
+.. module:: sphinx.ext.pngmath
+   :synopsis: Render math as PNG images.
+
+This extension renders math via LaTeX and dvipng_ into PNG images.  This of
+course means that the computer where the docs are built must have both programs
+available.
+
+There are various config values you can set to influence how the images are built:
+
+.. confval:: pngmath_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`` 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
+   :program:`sphinx-build` command line via the :option:`-D` option should be
+   preferable, like this::
+
+      sphinx-build -b html -D pngmath_latex=C:\tex\latex.exe . _build/html
+
+.. confval:: pngmath_dvipng
+
+   The command name with which 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.
+
+.. confval:: pngmath_latex_preamble
+
+   Additional LaTeX code to put into the preamble of the short LaTeX files that
+   are used to translate the math snippets.  This is empty by default.  Use it
+   e.g. to add more packages whose commands you want to use in the math.
+
+.. confval:: pngmath_dvipng_args
+
+   Additional arguments to give to dvipng, as a list.  This is empty by default.
+   Arguments you might want to add here are e.g. ``['-bg', 'Transparent']``,
+   which produces PNGs with a transparent background.  This is not enabled by
+   default because some Internet Explorer versions don't like transparent PNGs.
+
+.. confval:: pngmath_use_preview
+
+   ``dvipng`` has the ability to determine the "depth" of the rendered text: for
+   example, when typesetting a fraction inline, the baseline of surrounding text
+   should not be flush with the bottom of the image, rather the image should
+   extend a bit below the baseline.  This is what TeX calls "depth".  When this
+   is enabled, the images put into the HTML document will get a
+   ``vertical-align`` style that correctly aligns the baselines.
+
+   Unfortunately, this only works when the `preview-latex package`_ is
+   installed.  Therefore, the default for this option is ``False``.
+
+
+:mod:`sphinx.ext.jsmath` -- Render math via JavaScript
+------------------------------------------------------
+
+.. module:: sphinx.ext.jsmath
+   :synopsis: Render math via JavaScript.
+
+This extension puts math as-is into the HTML files.  The JavaScript package
+jsMath_ is then loaded and transforms the LaTeX markup to readable math live in
+the browser.
+
+Because jsMath (and the necessary fonts) is very large, it is not included in
+Sphinx.  You must install it yourself, and give Sphinx its path in this config
+value:
+
+.. confval:: 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 root of the built docs.
+
+   For example, if you put JSMath into the static path of the Sphinx docs, this
+   value would be ``_static/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.
+
+
+.. _dvipng: http://savannah.nongnu.org/projects/dvipng/
+.. _jsMath: http://www.math.union.edu/~dpvc/jsmath/
+.. _preview-latex package: http://www.gnu.org/software/auctex/preview-latex.html
+.. _AmSMath LaTeX package: http://www.ams.org/tex/amslatex.html