<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Math support in Sphinx — Sphinx v1.0.7 documentation</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.0.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Sphinx v1.0.7 documentation"
href="../_static/opensearch.xml"/>
<link rel="top" title="Sphinx v1.0.7 documentation" href="../index.html" />
<link rel="up" title="Sphinx Extensions" href="../extensions.html" />
<link rel="next" title="sphinx.ext.graphviz – Add Graphviz graphs" href="graphviz.html" />
<link rel="prev" title="sphinx.ext.intersphinx – Link to other projects’ documentation" href="intersphinx.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head>
<body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<img src="../_static/sphinx.png" alt="Sphinx logo" />
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="graphviz.html" title="sphinx.ext.graphviz – Add Graphviz graphs"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="intersphinx.html" title="sphinx.ext.intersphinx – Link to other projects’ documentation"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="../extensions.html" accesskey="U">Sphinx Extensions</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Math support in Sphinx</a><ul>
<li><a class="reference internal" href="#module-sphinx.ext.pngmath"><tt class="docutils literal"><span class="pre">sphinx.ext.pngmath</span></tt> – Render math as PNG images</a></li>
<li><a class="reference internal" href="#module-sphinx.ext.jsmath"><tt class="docutils literal"><span class="pre">sphinx.ext.jsmath</span></tt> – Render math via JavaScript</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="intersphinx.html"
title="previous chapter"><tt class="docutils literal docutils literal docutils literal"><span class="pre">sphinx.ext.intersphinx</span></tt> – Link to other projects’ documentation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="graphviz.html"
title="next chapter"><tt class="docutils literal docutils literal docutils literal"><span class="pre">sphinx.ext.graphviz</span></tt> – Add Graphviz graphs</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/ext/math.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-sphinx.ext.mathbase">
<span id="math-support-in-sphinx"></span><h1>Math support in Sphinx<a class="headerlink" href="#module-sphinx.ext.mathbase" title="Permalink to this headline">¶</a></h1>
<p class="versionadded">
<span class="versionmodified">New in version 0.5.</span></p>
<p>Since mathematical notation isn’t natively supported by HTML in any way, Sphinx
supports math in documentation with two extensions.</p>
<p>The basic math support that is common to both extensions is contained in
<a class="reference internal" href="#module-sphinx.ext.mathbase" title="sphinx.ext.mathbase: Common math support for pngmath and jsmath."><tt class="xref py py-mod docutils literal"><span class="pre">sphinx.ext.mathbase</span></tt></a>. Other math support extensions should,
if possible, reuse that support too.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#module-sphinx.ext.mathbase" title="sphinx.ext.mathbase: Common math support for pngmath and jsmath."><tt class="xref py py-mod docutils literal"><span class="pre">mathbase</span></tt></a> is not meant to be added to the <a class="reference internal" href="../config.html#confval-extensions"><tt class="xref std std-confval docutils literal"><span class="pre">extensions</span></tt></a> config
value, instead, use either <a class="reference internal" href="#module-sphinx.ext.pngmath" title="sphinx.ext.pngmath: Render math as PNG images."><tt class="xref py py-mod docutils literal"><span class="pre">sphinx.ext.pngmath</span></tt></a> or
<a class="reference internal" href="#module-sphinx.ext.jsmath" title="sphinx.ext.jsmath: Render math via JavaScript."><tt class="xref py py-mod docutils literal"><span class="pre">sphinx.ext.jsmath</span></tt></a> as described below.</p>
</div>
<p>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.</p>
<p><a class="reference internal" href="#module-sphinx.ext.mathbase" title="sphinx.ext.mathbase: Common math support for pngmath and jsmath."><tt class="xref py py-mod docutils literal"><span class="pre">mathbase</span></tt></a> defines these new markup elements:</p>
<dl class="role">
<dt id="role-math">
<tt class="descname">:math:</tt><a class="headerlink" href="#role-math" title="Permalink to this definition">¶</a></dt>
<dd><p>Role for inline math. Use like this:</p>
<div class="highlight-rest"><pre>Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.</pre>
</div>
</dd></dl>
<dl class="directive">
<dt id="directive-math">
<tt class="descname">.. math::</tt><a class="headerlink" href="#directive-math" title="Permalink to this definition">¶</a></dt>
<dd><p>Directive for displayed math (math that takes the whole line for itself).</p>
<p>The directive supports multiple equations, which should be separated by a
blank line:</p>
<div class="highlight-rest"><pre>.. math::
(a + b)^2 = a^2 + 2ab + b^2
(a - b)^2 = a^2 - 2ab + b^2</pre>
</div>
<p>In addition, each single equation is set within a <tt class="docutils literal"><span class="pre">split</span></tt> environment,
which means that you can have multiple aligned lines in an equation,
aligned at <tt class="docutils literal"><span class="pre">&</span></tt> and separated by <tt class="docutils literal"><span class="pre">\\</span></tt>:</p>
<div class="highlight-rest"><pre>.. math::
(a + b)^2 &= (a + b)(a + b) \\
&= a^2 + 2ab + b^2</pre>
</div>
<p>For more details, look into the documentation of the <a class="reference external" href="http://www.ams.org/tex/amslatex.html">AmSMath LaTeX
package</a>.</p>
<p>When the math is only one line of text, it can also be given as a directive
argument:</p>
<div class="highlight-rest"><pre>.. math:: (a + b)^2 = a^2 + 2ab + b^2</pre>
</div>
<p>Normally, equations are not numbered. If you want your equation to get a
number, use the <tt class="docutils literal"><span class="pre">label</span></tt> 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 <tt class="xref rst rst-role docutils literal"><span class="pre">eqref</span></tt> for an example. The numbering style depends
on the output format.</p>
<p>There is also an option <tt class="docutils literal"><span class="pre">nowrap</span></tt> that prevents any wrapping of the given
math in a math environment. When you give this option, you must make sure
yourself that the math is properly set up. For example:</p>
<div class="highlight-rest"><pre>.. math::
:nowrap:
\begin{eqnarray}
y & = & ax^2 + bx + c \\
f(x) & = & x^2 + 2xy + y^2
\end{eqnarray}</pre>
</div>
</dd></dl>
<dl class="role">
<dt id="role-eq">
<tt class="descname">:eq:</tt><a class="headerlink" href="#role-eq" title="Permalink to this definition">¶</a></dt>
<dd><p>Role for cross-referencing equations via their label. This currently works
only within the same document. Example:</p>
<div class="highlight-rest"><pre>.. math:: e^{i\pi} + 1 = 0
:label: euler
Euler's identity, equation :eq:`euler`, was elected one of the most
beautiful mathematical formulas.</pre>
</div>
</dd></dl>
<div class="section" id="module-sphinx.ext.pngmath">
<span id="sphinx-ext-pngmath-render-math-as-png-images"></span><h2><a class="reference internal" href="#module-sphinx.ext.pngmath" title="sphinx.ext.pngmath: Render math as PNG images."><tt class="xref py py-mod docutils literal"><span class="pre">sphinx.ext.pngmath</span></tt></a> – Render math as PNG images<a class="headerlink" href="#module-sphinx.ext.pngmath" title="Permalink to this headline">¶</a></h2>
<p>This extension renders math via LaTeX and <a class="reference external" href="http://savannah.nongnu.org/projects/dvipng/">dvipng</a> into PNG images. This of
course means that the computer where the docs are built must have both programs
available.</p>
<p>There are various config values you can set to influence how the images are built:</p>
<dl class="confval">
<dt id="confval-pngmath_latex">
<tt class="descname">pngmath_latex</tt><a class="headerlink" href="#confval-pngmath_latex" title="Permalink to this definition">¶</a></dt>
<dd><p>The command name with which to invoke LaTeX. The default is <tt class="docutils literal"><span class="pre">'latex'</span></tt>; you
may need to set this to a full path if <tt class="docutils literal"><span class="pre">latex</span></tt> is not in the executable
search path.</p>
<p>Since this setting is not portable from system to system, it is normally not
useful to set it in <tt class="docutils literal"><span class="pre">conf.py</span></tt>; rather, giving it on the
<strong class="program">sphinx-build</strong> command line via the <a class="reference internal" href="../invocation.html#cmdoption-D"><em class="xref std std-option">-D</em></a> option should be
preferable, like this:</p>
<div class="highlight-rest"><pre>sphinx-build -b html -D pngmath_latex=C:\tex\latex.exe . _build/html</pre>
</div>
<p class="versionchanged">
<span class="versionmodified">Changed in version 0.5.1: </span>This value should only contain the path to the latex executable, not
further arguments; use <a class="reference internal" href="#confval-pngmath_latex_args"><tt class="xref std std-confval docutils literal"><span class="pre">pngmath_latex_args</span></tt></a> for that purpose.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-pngmath_dvipng">
<tt class="descname">pngmath_dvipng</tt><a class="headerlink" href="#confval-pngmath_dvipng" title="Permalink to this definition">¶</a></dt>
<dd><p>The command name with which to invoke <tt class="docutils literal"><span class="pre">dvipng</span></tt>. The default is
<tt class="docutils literal"><span class="pre">'dvipng'</span></tt>; you may need to set this to a full path if <tt class="docutils literal"><span class="pre">dvipng</span></tt> is not in
the executable search path.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-pngmath_latex_args">
<tt class="descname">pngmath_latex_args</tt><a class="headerlink" href="#confval-pngmath_latex_args" title="Permalink to this definition">¶</a></dt>
<dd><p>Additional arguments to give to latex, as a list. The default is an empty
list.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.5.1.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-pngmath_latex_preamble">
<tt class="descname">pngmath_latex_preamble</tt><a class="headerlink" href="#confval-pngmath_latex_preamble" title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-pngmath_dvipng_args">
<tt class="descname">pngmath_dvipng_args</tt><a class="headerlink" href="#confval-pngmath_dvipng_args" title="Permalink to this definition">¶</a></dt>
<dd><p>Additional arguments to give to dvipng, as a list. The default value is
<tt class="docutils literal"><span class="pre">['-gamma</span> <span class="pre">1.5',</span> <span class="pre">'-D</span> <span class="pre">110']</span></tt> which makes the image a bit darker and larger
then it is by default.</p>
<p>An arguments you might want to add here is e.g. <tt class="docutils literal"><span class="pre">'-bg</span> <span class="pre">Transparent'</span></tt>,
which produces PNGs with a transparent background. This is not enabled by
default because some Internet Explorer versions don’t like transparent PNGs.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>When you “add” an argument, you need to reproduce the default arguments if
you want to keep them; that is, like this:</p>
<div class="last highlight-rest"><pre>pngmath_dvipng_args = ['-gamma 1.5', '-D 110', '-bg Transparent']</pre>
</div>
</div>
</dd></dl>
<dl class="confval">
<dt id="confval-pngmath_use_preview">
<tt class="descname">pngmath_use_preview</tt><a class="headerlink" href="#confval-pngmath_use_preview" title="Permalink to this definition">¶</a></dt>
<dd><p><tt class="docutils literal"><span class="pre">dvipng</span></tt> 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
<tt class="docutils literal"><span class="pre">vertical-align</span></tt> style that correctly aligns the baselines.</p>
<p>Unfortunately, this only works when the <a class="reference external" href="http://www.gnu.org/software/auctex/preview-latex.html">preview-latex package</a> is
installed. Therefore, the default for this option is <tt class="xref docutils literal"><span class="pre">False</span></tt>.</p>
</dd></dl>
</div>
<div class="section" id="module-sphinx.ext.jsmath">
<span id="sphinx-ext-jsmath-render-math-via-javascript"></span><h2><a class="reference internal" href="#module-sphinx.ext.jsmath" title="sphinx.ext.jsmath: Render math via JavaScript."><tt class="xref py py-mod docutils literal"><span class="pre">sphinx.ext.jsmath</span></tt></a> – Render math via JavaScript<a class="headerlink" href="#module-sphinx.ext.jsmath" title="Permalink to this headline">¶</a></h2>
<p>This extension puts math as-is into the HTML files. The JavaScript package
<a class="reference external" href="http://www.math.union.edu/~dpvc/jsmath/">jsMath</a> is then loaded and transforms the LaTeX markup to readable math live in
the browser.</p>
<p>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:</p>
<dl class="confval">
<dt id="confval-jsmath_path">
<tt class="descname">jsmath_path</tt><a class="headerlink" href="#confval-jsmath_path" title="Permalink to this definition">¶</a></dt>
<dd><p>The path to the JavaScript file to include in the HTML files in order to load
JSMath. There is no default.</p>
<p>The path can be absolute or relative; if it is relative, it is relative to
the <tt class="docutils literal"><span class="pre">_static</span></tt> directory of the built docs.</p>
<p>For example, if you put JSMath into the static path of the Sphinx docs, this
value would be <tt class="docutils literal"><span class="pre">jsMath/easy/load.js</span></tt>. If you host more than one
Sphinx documentation set on one server, it is advisable to install jsMath in
a shared location.</p>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="graphviz.html" title="sphinx.ext.graphviz – Add Graphviz graphs"
>next</a> |</li>
<li class="right" >
<a href="intersphinx.html" title="sphinx.ext.intersphinx – Link to other projects’ documentation"
>previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="../extensions.html" >Sphinx Extensions</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2007-2011, Georg Brandl.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
2b39e69e45f9a0b2b3aece7339c56216
>
files
>
90
