Sphinx LaTeX markup limitations

Question

I'm trying to do three really basic things inside of a multi-line math mode in Sphinx (version 1.1.2-1).

1. Write underscores as part of my variable names even in math mode;
2. Use the \big, \biggl, etc., delimiters to make large brackets and parentheses;
3. and include regular text as part of equations.

Note the following two things. (1) I am using a raw string in my Python code for the Sphinx-markup documentation, so extra backslashes are not needed for escape characters, and (2) I am not doing inline math mode, which is delimited like this in Sphinx:

:math:`Some math stuff goes here` regular text could go here...

Instead, I am doing multi-line stuff, often like eqnarray in LaTeX:

.. math::
    DividendYield &=& \frac{DVT(t)}{CurrentMarketCap} \\
    Avg_Assets &=& \biggl( A/B \biggr) \textrm { when B is not zero...}

Currently, I get Sphinx errors (and the generated doc pages look like gibberish), that say things like:

Unknown LaTeX command: textrm

The same happens for \biggl. For the underscore, it just always interprets it as if I am denoting a subscript, but if I use \textunderscore or other tricks then it throws the same sorts of errors as above.

Underscores within math mode, the textrm command, and big delimiters are extremely basic parts of every native TeX package I've ever used. So why are they inaccessible through Sphinx?

Update

One particular Python file that I am working on calculates Book Equity data for me. So below, when you see the stuff about BookEquity, that's the reference. I can't run our build-docs process except through a version control system, so making a reproducible error was easiest if I just modified an existing file.

However, all I did was to add the following class function in my code, with a simple docstring.

def foo(self):
    r"""
    Sample docstring

    .. math::
        Ax &=& b \\
        Cx &=& \biggl(\frac{x/y}\biggr) \textrm{ if y is not zero.}
    """
    pass

And then the image below is the output coming from building the docs with Sphinx 1.1.2-1.

If you right-click and select 'view image' you can see a better version.

Answer 1

You have to edit the standard configuration file that sphinx-quickstart creates, otherwise sphinx will barf at math blocks. In the file conf.py, I changed

extensions = []

to

extensions = ['sphinx.ext.pngmath']

After that the following rst file more-or-less worked;

.. foo documentation master file, created by
   sphinx-quickstart on Thu Oct 25 11:04:31 2012.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to foo's documentation!
===============================

Contents:

.. toctree::
   :maxdepth: 2

This is the first chapter
=========================

Instead, I am doing multi-line stuff, often like eqnarray in LaTeX:

.. math::
    DividendYield &=& \frac{DVT(t)}{CurrentMarketCap} \\
    Avg_Assets &=& \biggl( A/B \biggr) \textrm { when B is not zero...}

It produced the following LaTeX code for the math fragment:

\chapter{This is the first chapter}
\label{index:welcome-to-foo-s-documentation}\label{index:this-is-the-first-chapter}
Instead, I am doing multi-line stuff, often like eqnarray in LaTeX:
\begin{gather}
\begin{split}DividendYield &=& \frac{DVT(t)}{CurrentMarketCap} \\
Avg_Assets &=& \biggl( A/B \biggr) \textrm { when B is not zero...}\end{split}\notag\\\begin{split}\end{split}\notag
\end{gather}

The choice of using the combination of split and gather seems a bit weird to me, and obviously doesn't work well with the code you wrote for eqnarray, but this is hardcoded in Sphinx.

Running pdflatex did stop at \end{gather}, with the error Extra alignment tab has been changed to \cr. but I was able to proceed past that by entering nonstopmode. This give me the following result:

While there is still something wrong with the alignment (because of the differences between the split and eqnarray environments), the textrm and biggl seem to work fine. (Note that you'll still have to escape the underscore in Average_Assets, but that is par for the course, AFAICT).

You might get away with postprocessing the generated LaTeX code, e.g. by replacing \begin{gather}\begin{split} and \end{split}\notag\\\begin{split}\end{split}\notag\end{gather} by the math environment of your choice.

Update:

The screenshot from the update seems to be from a webpage, not a LaTeX document! So it looks to me that what is producing the error is the handler that converts the LaTeX math notation so something a browser can show. That will be probably be either MathJax or jsMath. From looking at the code, pngmath would produce other error messages. According to this page, your code snippet should work in mathjax. From the jsMath symbols page, it doesn't look like jsmath supports \Biggl. So my best guess is that SPhinx is configured to use jsMath. A peek at the source of the generated web page should tell you what is used to render the math. If my guess is correct, switching the configuration to use mathjax and slightly adapting your equation might fix the problem.

Update2: I can definitely confirm that it works fine with MathJax (see below). I don't have jsMath installed, though.