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 文件为我计算账面净值数据。 所以在下面，当您看到有关 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']

之后，以下 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. 但我能够通过进入非停止模式继续过去。 这给了我以下结果：

虽然对齐仍然有问题（因为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。

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

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

原答案

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

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

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

我想我还记得 docutils 开发人员对这个主题的一些批评：docutils 有一个 latex builder（似乎“更好”），但是 sphinx 不使用这个构建器。

曾经在邮件列表中发布了一个名为relatex （ 链接）的项目， relatex对sphinx 创建的latex 代码进行后处理。 但我不确定开发状态。 我使用了我自己的代码，我在这里提供了它（不幸的是它是德语和英语的混合体）。 我认为它不是很有用，因为我认为后处理 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 中都可以很好地呈现。