狮身人面像LaTeX的标记限制(Sphinx LaTeX markup limitations)

我试图做在狮身人面像多行数学模式（版本1.1.2-1）的内部的三个很基本的东西。

1. 写强调因为即使在数学模式我的变量名的一部分;
2. 使用\big ， \biggl等，分隔符，使大括号和括号;
3. 而包括定期文本作为公式的一部分。

请注意以下两点。 （1）我使用的狮身人面像的标记文档我的Python代码原始字符串，因此不需要进行转义字符额外的反斜杠，和（2）我没有做内联数学模式，这是在狮身人面像分隔是这样的：

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

取而代之的是，我做的多行的东西，往往喜欢eqnarray LaTeX中：

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

目前，我得到狮身人面像的错误（和生成的文档页面看起来像废话），该说的东西，如：

Unknown LaTeX command: textrm

同样的情况，为\biggl 。 对于下划线，它只是始终将其解释为，如果我表示一个下标，但如果我用\textunderscore或其他的技巧则抛出相同类型的错误如上。

数学模式，在内部强调textrm命令，大分隔符是极其我曾经使用过的每一个原生的TeX包的基本组成部分。 那么，为什么他们不能访问过狮身人面像？

更新

我的工作在一个特定的Python的文件计算我书股票数据。 所以下面，当你看到有关BookEquity的东西，那就是参考。 我无法运行我们的构建，文档处理，除非通过版本控制系统，所以做一个可重复的错误是最简单的，如果我只是修改了现有的文件。

然而，我所做的只是添加下面的类的功能在我的代码，用一个简单的文档字符串。

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

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

然后下面的图片是从狮身人面像1.1.2-1建立文档来输出。

如果你右击并选择“查看图片”，你可以看到一个更好的版本。

Answer 1:

你要编辑的标准配置文件， sphinx-quickstart创建，否则狮身人面像将在数学块BARF。 在文件conf.py ，我改变

extensions = []

至

extensions = ['sphinx.ext.pngmath']

之后，下面的第一个文件更多或更少的工作;

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

它产生的数学片段下面乳胶代码：

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

使用和收集拆分的组合的选择似乎有点怪我，显然不符合你eqnarray的写的代码很好地工作，但是这是在狮身人面像硬编码。

运行pdflatex并停止在\end{gather}与错误Extra alignment tab has been changed to \cr. 但我可以通过输入nonstopmode继续过去那种。 这给我了以下结果：

虽然仍然有一些错误的定位（因为之间的差异split和eqnarray环境）中，TEXTRM和biggl似乎很好地工作。 （请注意，您仍然有逃避下划线Average_Assets ，但这是意料之中的事，AFAICT）。

你也许可以侥幸逃脱后处理生成的LaTeX的代码，例如通过替换\begin{gather}\begin{split}和\end{split}\notag\\\begin{split}\end{split}\notag\end{gather}通过您所选择的数学环境。

更新 ：

从更新的截图似乎是从一个网页，而不是一个LaTeX文档！ 所以在我看来，什么是产生错误是转换LaTeX的数学符号等等一些浏览器可以显示的处理程序。 这将可能是要么MathJax或jsMath 。 从看代码， pngmath会产生其他错误消息。 根据这个页面 ，你的代码段应在mathjax工作。 从jsMath符号页面 ，它看起来并不像jsmath支持\Biggl 。 所以我最好的猜测是，狮身人面像被配置为使用jsMath。 在所生成的网页的源偷看应该告诉你的是用于呈现数学内容。 如果我的猜测是正确的，切换配置使用mathjax稍微调整你的公式可能会解决问题。

UPDATE2：我可以肯定地确认它正常工作与MathJax（见下文）。 我没有安装jsMath，虽然。

Answer 2:

Update

As mentioned, sphinx uses gather and split for math mode. According to the AMS math guide split takes 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

renders fine with latexpdf and to html with the MathJax extension.

Note that I used \_ for the underscore in math mode , which worked, but \textunderscore didn't work (You have to load additional packages I think, see this question on tex.stackexchange.com). So as it comes out, I think your question is clearly a Tex question.

I don't remove my previous answer, however it is only applicable for the latex builder, not for the html builder.

Original answer

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

The problem is, that there is no simple way to modify the latex source it produces. You have to post-process the latex source to get "scientific" grade latex code.

Sphinx is designed for html docs (and by web developers I think), latex (and scientific "problems" like numbered figures, tables and equations) doesn't seem to be the main focus of the project. By the way, your code renders fine to html with the mathjax extension.

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

There was once an announcement of a project called relatex (link) on the mailing list to post-process the latex code created by sphinx. But I'm not sure about the development status. I used my own code, which I made available here (unfortunately it is a mixture of German an English). I don't think that it is very useful, because I decided that it is to complicated to post-process sphinx latex and I switched to pure latex. So I didn't developed it further. However the basic steps are

• create your own latex style and template
• let sphinx create it's latex code
• post-process the latex code and paste it into your template
• use a building system for LaTeX to generate the pdf from your code

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

Answer 3:

现在（2016）狮身人面像数学指令有选项:nowrap:返回完全控制权交给用户，所以只是做

.. math::
   :nowrap:

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

呈现HTML和latexpdf罚款。

文章来源: Sphinx LaTeX markup limitations