Sphinx LaTeX markup limitations

Question

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

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

Pay attention to the following two things. (1) I use the raw string in my Python code for documentation on Sphinx markup, so no extra backslashes are required for escape characters, and (2) I don't run the built-in math mode, which is similar to this in Sphinx:

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

Instead, I make multiline entries, often like eqnarray in LaTeX:

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

I am currently getting Sphinx errors (and the generated document pages look like gibberish) that say things like:

 Unknown LaTeX command: textrm 

The same thing happens for \biggl . For underlining, he simply always interprets it as if I were designating an index, but if I use \textunderscore or other tricks, it throws the same types of errors as above.

The math underline, the textrm command textrm and the large delimiters are extremely basic parts of every native TeX package I have ever used. So why are they inaccessible through the Sphinx?

Update

One particular Python file I'm working on calculates Book Equity data for me. So below, when you see material about BookEquity, this is a link. I can’t start our documentation process except through the version control system, so it was easiest to make a reproducible error if I just changed an existing file.

However, all I did was add the following class function to 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 from creating documents using Sphinx 1.1.2-1.

If you right-click and select "View Image", you can see the best version.

Answer 1

You must edit the standard configuration file that sphinx-quickstart creates, otherwise sphinx will be barf in the math blocks. In the conf.py file conf.py I changed

 extensions = [] 

to

 extensions = ['sphinx.ext.pngmath'] 

After that, more or less the following file 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 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...} 

He 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} 

Choosing to use a combination of split and gather seems a little strange to me and, obviously, doesn't work very well with the code you wrote for eqnarray, but it is hardcoded in Sphinx.

Running pdflatex stopped at \end{gather} , with the error Extra alignment tab has been changed to \cr. but I was able to continue this by introducing nonstopmode. This gives me the following result:

Although there is still something wrong with alignment (due to the differences between split and eqnarray ), textrm and biggl are working fine. (Note that you still have to avoid underscores in Average_Assets , but this is consistent with the course, AFAICT).

You can get away with post-processing the generated LaTeX code, for example. replacing \begin{gather}\begin{split} and \end{split}\notag\\\begin{split}\end{split}\notag\end{gather} with the math environment of your choice.

Update

The screenshot from the update seems to be from a web page, not from a LaTeX document! Therefore, it seems to me that what creates the error is a handler that converts the mathematical notation of LaTeX, so there is something that the browser can show. It will probably be either MathJax or jsMath . After reviewing the code, pngmath will generate other error messages. According to this page , your code snippet should work in mathjax. From the jsMath character page , this does not look like jsmath \Biggl . Therefore, I believe that SPhinx is configured to use jsMath. Take a look at the source of the webpage you created to tell you what is used to visualize math. If my guess is correct, switching the configuration to using mathjax and slightly adapting your equation may solve the problem.

Update2 . I can definitely confirm that it works great with MathJax (see below). However, I do not have jsMath.

Answer 2

Update

As mentioned, sphinx uses gather and split for math mode. According to AMS, the math guide split accepts a single $ sign. So,

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

with foo defined as

 def foo(self): r"""Sample docstring .. math:: Ax &= b \\ Cx &= \biggl( \frac{x}{y} \biggr) \textrm{ if y is not zero.} """ pass 

does fine with latexpdf and html with the MathJax extension .

Note that I used \_ for underlining in math mode, which worked, but \textunderscore did not work (you need to download additional packages, I think, see this question on tex.stackexchange.com). Since this comes out, I think your question is clearly a Tex question.

I am not deleting my previous answer, however it is applicable only to the latex builder, and not to the html constructor.

Original answer

Sphinx produces "unusual" latex code. It uses gather and split for equations (look at the source of latex that it generates).

The problem is that there is no easy way to modify the source of latex that it produces. You must post-process the latex source to get a “scientific” latex code.

Sphinx is intended for html documents (and, according to web developers), latex (and scientific "problems" such as numeric numbers, tables and equations), apparently, are not the main goal of the project. By the way, your code displays html perfectly with the mathjax extension.

I think I remember some criticism from the docutils developers on this topic: docutils has a latex builder (which seems "better"), but this builder is not used by sphinx.

It was once announced a project called relatex ( link ) on the mailing list for subsequent processing of latex code on the sphinx. But I'm not sure about the development status. I used my own code that I provided here (unfortunately this is a mixture of German and English). I do not think this is very useful because I decided it was difficult to process the sphinx latex, and I switched to pure latex. Therefore, I did not develop it further. However the main steps

• create your own style and latex pattern
• let sphinx create its latex code
• after processing the latex code and paste it into your template
• use the building system for LaTeX to create pdf code from your code.

I adapted the sphinx Makefile to do this in one step. As a building system, I used rubber (currently I would use latexmk ).

Answer 3

Now (2016) the Sphinx Math directive has the option :nowrap: which returns full control to the user, so it’s just

 .. math:: :nowrap: \begin{eqnarray} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{eqnarray} 

displays in both html and latexpdf.