python - Sphinx LaTeX 标记限制

Question

我正在尝试在 Sphinx(版本 1.1.2-1)中的多行数学模式中做三件非常基本的事情。

1. 即使在数学模式下，也可以将下划线作为变量名的一部分；
2. 使用\big、\biggl等定界符组成大括号和圆括号；
3. 并将常规文本作为方程式的一部分。

注意以下两点。 (1) 我在 Sphinx 标记文档的 Python 代码中使用原始字符串，因此转义字符不需要额外的反斜杠，并且 (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 文件会为我计算账面净值数据。所以在下面，当你看到有关 BookEquity 的内容时，这就是引用。除非通过版本控制系统，否则我无法运行我们的构建文档过程，因此如果我只是修改现有文件，则最容易产生可重现的错误。

但是，我所做的只是在我的代码中添加以下类函数，以及一个简单的文档字符串。

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 构建文档的输出。

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

Answer 1

您必须编辑 sphinx-quickstart 创建的标准配置文件，否则 sphinx 会在数学 block 处呕吐。在文件 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...}

它为数学片段生成了以下 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. 但我能够继续通过进入不间断模式。这给了我以下结果:

虽然对齐仍有问题(因为 split 和 eqnarray 环境之间的差异)，但 textrm 和 biggl 似乎工作正常。 (请注意，您仍然需要在 Average_Assets 中转义下划线，但这对类(class)来说是正常的，AFAICT)。

您可能对生成的 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 并稍微调整您的等式可能会解决问题。

Update2:我可以肯定地确认它可以与 MathJax 一起正常工作(见下文)。不过，我没有安装 jsMath。