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

相反，我正在做多行的东西，通常就像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 文件为我计算账面净值数据。所以下面，当你看到关于 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 会在数学块上吐槽。在文件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 和 collect 组合的选择对我来说似乎有点奇怪，并且显然不适用于您为 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 数学符号，以便浏览器可以显示。那可能是MathJaxor jsMath。通过查看代码，pngmath会产生其他错误消息。根据这个页面，您的代码片段应该在 mathjax 中工作。从jsMath 符号页面，它看起来不像 jsmath 支持\Biggl. 所以我最好的猜测是 SPhinx 被配置为使用 jsMath。查看生成的网页的来源应该会告诉您用于呈现数学的内容。如果我的猜测是正确的，将配置切换为使用 mathjax 并稍微调整您的方程式可能会解决问题。

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

Answer 2

更新

如前所述，sphinx 使用gatherandsplit用于数学模式。根据AMS 数学指南，拆分需要一个$符号。所以

.. 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没有用（我认为您必须加载其他包，请参阅 tex.stackexchange.com 上的这个问题）。所以当它出现时，我认为你的问题显然是一个Tex问题。

我没有删除我之前的答案，但是它仅适用于乳胶生成器，不适用于 html 生成器。

原始答案

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

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

Sphinx 是为 html 文档设计的（我认为是由 web 开发人员设计的），乳胶（以及像编号数字、表格和方程式这样的科学“问题”）似乎并不是该项目的主要重点。顺便说一句，您的代码可以很好地呈现为带有 mathjax 扩展的 html。

我想我也记得 docutils 开发人员对这个主题的一些批评：docutils 有一个乳胶生成器（这似乎“更好”），但是 sphinx 不使用这个生成器。

曾经在邮件列表中发布了一个名为relatex( link ) 的项目，用于对 sphinx 创建的乳胶代码进行后处理。但我不确定发展状况。我使用了我自己的代码，我在这里提供了它（不幸的是它是德语和英语的混合体）。我认为它不是很有用，因为我认为后处理 sphinx 乳胶很复杂，所以我改用纯乳胶。所以我没有进一步开发它。但是基本步骤是

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

我调整了 sphinx Makefile 以一步完成。作为我使用的建筑系统rubber（现在我会使用latexmk）。

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 中都可以很好地呈现。