Sphinx LaTeX标记限制

Question

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

1. 即使在数学模式下，下划线也应作为变量名的一部分写入；
2. 使用\big，\biggl等等，分隔符，使大括号和括号;
3. 并将常规文本作为等式的一部分。

请注意以下两件事。（1）我在Python代码中使用了原始字符串作为Sphinx-
markup文档，因此转义字符不需要多余的反斜杠，并且（2）我没有做内联数学模式，在Sphinx中这样分隔：

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

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

Unknown LaTeX command: textrm

也会发生同样的情况\biggl。对于下划线，它总是总是将其解释为好像我在指示下标，但是如果我使用\textunderscore或其他技巧，则会引发与上述相同的错误。

数学模式下的下划线，textrm命令和大分隔符是我曾经使用过的每个本机TeX软件包的极其基本的部分。那么，为什么通过Sphinx无法访问它们？

更新资料

我正在处理的一个特定Python文件会为我计算Book
Equity数据。因此，在下面，当您看到有关BookEquity的内容时，这就是参考。除了通过版本控制系统，我无法运行我们的build-
docs流程，因此，如果我只是修改现有文件，则最容易产生可再现的错误。

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

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创建的标准配置文件，否则，狮身人面像将对数学块产生干扰。在文件中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}

对我来说，使用拆分和聚集的组合选择似乎有点奇怪，并且显然不能与您为eqnarray编写的代码一起很好地工作，但这在Sphinx中是硬编码的。

运行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。因此，我最好的猜测是SPhinx配置为使用jsMath。窥视所生成网页的源应该告诉您用于渲染数学的内容。如果我的猜测是正确的，则将配置切换为使用mathjax并稍微调整您的方程式可能会解决此问题。

Update2 ：我可以肯定地确认它可以与MathJax一起正常工作（请参见下文）。我没有安装jsMath。