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

相反，我正在做多行的事情，通常像LaTeX中的eqnarray：

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

目前，我收到Sphinx错误（生成的doc页面看起来像乱码），比如说：

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创建的标准配置文件，否则sphinx将在数学块处进行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...}

它为数学片段生成了以下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中的下划线，但这与课程AFAICT相同。

你可能会对生成的LaTeX代码进行后期处理，例如将\begin{gather}\begin{split}和\end{split}\notag\\\begin{split}\end{split}\notag\end{gather}替换为您选择的数学环境。

<强>更新：

更新的屏幕截图似乎是来自网页，而不是LaTeX文档！因此，在我看来产生错误的是处理程序，它转换LaTeX数学符号，以便浏览器可以显示。这可能是MathJax或jsMath。通过查看代码，pngmath会产生其他错误消息。根据{{​​3}}，您的代码段应该在mathjax中工作。从this page开始，它看起来不像jsmath支持\Biggl。所以我最好的猜测是SPhinx配置为使用jsMath。查看生成的网页的来源应该告诉您用于渲染数学的内容。如果我的猜测是正确的，切换配置以使用mathjax并略微调整您的等式可能会解决问题。

Update2 ：我绝对可以确认它与MathJax一起工作正常（见下文）。我没有安装jsMath。

Answer 2

<强>更新

如上所述，sphinx使用gather和split进行数学模式。根据{{​​3}}拆分需要一个$符号。所以

.. 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和使用AMS math guide的HTML进行渲染。

请注意，我在数学模式下使用\_作为下划线，但是\textunderscore不起作用（我必须加载其他包，请参阅tex上的MathJax extension .stackexchange.com）。 因此，我认为您的问题显然是Tex问题。

我没有删除我之前的答案，但它只适用于latex构建器，而不适用于html构建器。

原始回答

Sphinx产生“不寻常”的乳胶代码。它使用gather和split来表示方程式（查看它生成的乳胶源）。

问题是，没有简单的方法来修改它产生的乳胶源。您必须对胶乳来源进行后处理才能获得“科学”级乳胶代码。

Sphinx专为html文档设计（我认为是Web开发人员），乳胶（以及编号图，表格和方程式等科学“问题”）似乎不是该项目的主要关注点。顺便说一句，您的代码使用mathjax扩展名呈现为html。

我想我还记得docutils开发人员对这个话题的一些批评：docutils有一个乳胶构建器（看起来“更好”），但sphinx不使用这个构建器。

曾经在邮件列表上宣布了一个名为relatex（this question）的项目，用于对sphinx创建的乳胶代码进行后期处理。但我不确定发展状况。 我使用了自己的代码，我提供了link（不幸的是它是德语和英语的混合物）。我不认为这是非常有用的，因为我认为复制到后加工的sphinx乳胶并且我改用纯乳胶。所以我没有进一步发展它。但是基本步骤是

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

我改编了sphinx Makefile，只需一步即可完成。作为我使用的建筑系统here（现在我会使用rubber）。

Answer 3

现在（2016）Sphinx数学指令选项:nowrap:将完全控制权交给用户，所以只做

.. math::
   :nowrap:

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

在html和latexpdf中都可以正常显示。