Sphinx LaTeX标记的限制

Question

我正在尝试在Sphinx（版本1.1.2-1）的多行数学模式中完成三个非常基本的任务。

1. 即使在数学模式下，将下划线作为变量名的一部分编写；
2. 使用\big、\biggl等定界符来制作大括号和括号；
3. 并将常规文本包含在方程中。

请注意以下两点。 (1) 我在Python代码中使用原始字符串进行Sphinx标记文档，因此不需要额外的反斜杠来转义字符，(2) 我没有进行内联数学模式，它在Sphinx中的定界符如下：

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

相反，我正在进行多行操作，通常类似于LaTeX中的eqnarray：

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

目前，我收到Sphinx错误（生成的文档页面看起来像胡言乱语），显示的内容如下：

Unknown LaTeX command: textrm

同样的情况也会发生在\biggl中。对于下划线，它总是将其解释为下标符号，但如果我使用\textunderscore或其他技巧，则会出现与上述相同类型的错误。

在数学模式、textrm命令和大分隔符中使用下划线是我使用过的每个本地TeX包的基本部分。那么为什么它们在Sphinx中不可用呢？

更新

我正在处理一个特定的Python文件，该文件为我计算Book Equity数据。因此，在下面看到关于BookEquity的内容时，这就是参考资料。我无法通过版本控制系统以外的方式运行我们的build-docs流程，因此，如果我只是修改现有文件，使其出现可重复的错误，那么最简单的方法就是添加以下类函数到我的代码中，并附带一个简单的docstring。

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

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

下面的图片是使用Sphinx 1.1.2-1生成文档的输出结果。

如果您右键点击并选择“查看图像”，您可以看到更好的版本。

- ely

---

抱歉不知道Sphinx，但我认为下划线需要转义为\_，您可以尝试使用\text{}代替\textrm（需要amsmath包）。 - Peter Grill

你能发布一些生成的LaTeX代码吗？例如，你的例子中的代码。 - Roland Smith

我们有一个Tex/LaTeX网站：http://tex.stackexchange.com/，也许更适合您的问题。在那里四处看看，如果看起来很有前途，那么可以退还您的悬赏并将此问题迁移到那里。请标记以告知我们您是否要这样做。 - Kev

@EMS：输出数学内容的代码（mathbase.py）的最后更改是在1.1.2版本发布之前。因此，在1.1.2和1.1.3之间，该行为没有发生变化。 - Roland Smith

@EMS - 这确实让我有点惊讶，但话说回来，看起来你在这里得到了很好的帮助。 - Kev

Answer 1

你需要编辑由sphinx-quickstart创建的标准配置文件，否则sphinx将无法处理数学块。在conf.py文件中，我进行了更改。

extensions = []

到

extensions = ['sphinx.ext.pngmath']

之后，以下的rst文件更或多或少地有效;

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

它为数学片段生成了以下LaTeX代码：

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

使用split和gather的组合选择对我来说有点奇怪，显然与您为eqnarray编写的代码不兼容，但这是在Sphinx中硬编码的。

运行pdflatex确实停在了\end{gather}处，并显示错误Extra alignment tab has been changed to \cr. 但我能够通过输入nonstopmode来继续进行。这给了我以下结果：

虽然由于“split”和“eqnarray”环境之间的差异，对齐仍存在问题，但textrm和biggl似乎工作正常。请注意，您仍然需要转义“Average_Assets”中的下划线，但我认为这是例行公事。

您可以尝试后处理生成的LaTeX代码，例如通过将“\begin{gather}\begin{split}”和“\end{split}\notag\\\begin{split}\end{split}\notag\end{gather}”替换为所选的数学环境来解决问题。

更新：

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

更新2：我可以明确确认它在MathJax下运行良好（请参见下文）。虽然我没有安装jsMath。

- Roland Smith

---

谢谢，这非常有帮助。但是，我不需要做任何事情就可以通常渲染数学块。例如，我可以很好地制作多行数学块，只有像\textrm这样的特定命令会导致错误。您能解释一下这与需要pngmath dealie的需求一致吗？我将与我们这里的系统管理员核实此事，但这是一个有前途的线索。 - ely

是_sphinx_导致了错误还是_LaTeX_？从你的问题中我无法判断。 - Roland Smith

这真的很奇怪，因为我在 Sphinx 1.1.2 的源代码中搜索了“Unknown”、“LaTeX”或“command”这些词，但没有找到任何类似于你在问题中提到的错误信息。 - Roland Smith

请看更新。我犯了一个可重现的错误，并截取了Sphinx所说的内容的屏幕截图。 - ely

感谢您继续跟进此事。我会检查一下并尝试一下。听起来很有希望，可能是Sphinx后的错误。 - ely

Answer 2

更新

正如提到的，sphinx在数学模式中使用gather和split。根据 AMS数学指南，split只需要一个$符号。

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

定义了foo为

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

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

使用latexpdf可以很好地呈现，而使用MathJax扩展程序则可将其转换为HTML。

请注意，在数学模式下我使用了\_代替下划线，这是有效的，但\textunderscore无效（我认为您需要加载其他包，请参见this question在tex.stackexchange.com上）。因此，我认为您的问题显然是一个Tex问题。

我不会删除我的先前答案，但它仅适用于latex构建器，而不适用于html构建器。

Sphinx生成“异常”的latex代码。它使用gather和split来表示方程式（查看它生成的latex源代码）。

问题在于，没有简单的方法修改它生成的latex源代码。您必须对latex源代码进行后处理，以获得“科学级”latex代码。

Sphinx专为HTML文档设计（我认为是由Web开发人员），而latex（以及数字图表、表格和方程式等科学“问题”）似乎并非该项目的主要关注点。顺便说一下，您的代码可以通过mathjax扩展在html中呈现出来。

我记得docutils的开发者在这个问题上也有一些批评：docutils有一个latex builder（似乎更好），但sphinx没有使用这个builder。

曾经有一个名为relatex（link）的项目在邮件列表中宣布，用于后处理由sphinx创建的latex代码。但我不确定开发状态如何。 我使用了自己的代码，可以在here找到（不幸的是，它是德语和英语的混合体）。我认为它并不是非常有用，因为我决定后处理sphinx latex太过复杂，转而使用纯latex。所以我没有进一步开发它。然而，基本步骤如下：

• 创建自己的latex样式和模板
• 让sphinx创建它的latex代码
• 后处理latex代码并将其粘贴到您的模板中
• 使用LaTeX构建系统从您的代码生成pdf

我调整了Sphinx的Makefile以在单个步骤中完成此操作。作为构建系统，我使用了rubber（现在我会使用latexmk）。

- bmu

---

这对 Sphinx 的背景信息很有帮助。你能详细写一些关于特定的后处理 Sphinx 输出以便 TeX 渲染的过程吗？如果我可以编写一个 Python 脚本，在每次构建文档时自动执行该脚本，那将是一个好选择。 - ely

Answer 3

现在（2016年），Sphinx的数学指令有选项:nowrap:，可以完全控制给用户, 因此只需执行以下操作：

.. math::
   :nowrap:

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

在HTML和LaTeX PDF中都可以正确显示。

- kkumer