Sphinx乳胶标记限制

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：

.. 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包中非常基本的部分。为什么他们无法通过狮身人面像？

更新

我正在处理的一个特定Python文件为我计算帐面净值数据。所以下面，当你看到有关股本的东西，那就是参考。除了通过版本控制系统之外，我无法运行构建文档过程，因此，如果我只是修改了现有文件，那么生成可复制的错误是最容易的。

但是，我所做的只是在代码中添加了下面的类函数，使用了一个简单的docstring。

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

现在（2016）Sphinx math指令有选项:nowrap:将完全控制权返回给用户，因此只需

.. math::
   :nowrap:

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

在html和latexpdf中呈现精细。

Answer 2

您必须编辑sphinx-quickstart创建的标准配置文件，否则sphinx将在数学块上显示barf。在文件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...}

它为数学片段生成了以下乳胶代码：

\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）。

您可能会忘记对生成的乳胶代码进行后处理，例如用您选择的数学环境替换\begin{gather}\begin{split}和\end{split}\notag\\\begin{split}\end{split}\notag\end{gather}。

更新：

更新的截图似乎来自一个网页，而不是一个乳胶文件！所以在我看来，产生错误的是转换乳胶数学符号的处理程序，这样浏览器就可以显示一些东西。可能是MathJax或jsMath。从代码来看，pngmath将产生其他错误消息。根据this page，您的代码片段应该在mathjax中工作。从jsMath symbols page来看，jsmath不支持\Biggl。所以我最好的猜测是SPhinx被配置为使用jsMath。浏览一下生成的网页的源代码，就可以知道用来呈现数学的是什么。如果我的猜测是正确的，那么将配置切换为使用mathjax并稍微修改您的公式可能会解决问题。

Update2：我可以肯定它在MathJax上运行良好（见下文）。不过，我没有安装jsMath。

Answer 3

更新

如前所述，sphinx使用gather和split作为数学模式。根据AMS math guide分裂得到一个$符号。所以

.. 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 extension呈现html。

请注意，我在数学模式中使用了\_作为下划线，这很有效，但是\textunderscore不起作用（我认为您必须加载其他包，请参见tex.stackexchange.com上的this question）。 因此，我认为你的问题显然是一个Tex问题。

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

原始答案

狮身人面像产生“不寻常的”乳胶代码。它使用gather和split作为方程（查看它生成的乳胶源）。

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

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

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

有一次，在邮件列表中有一个名为relatex（link）的项目宣布要对sphinx创建的乳胶代码进行后期处理。但我不确定发展状况。 我使用了自己的代码，我提供了here（不幸的是，它是德语和英语的混合体）。我不认为这是非常有用的，因为我决定它是复杂的后处理狮身人面像乳胶和我切换到纯乳胶。所以我没有进一步发展。然而，基本步骤是

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

我修改了sphinx Makefile来在一个步骤中完成这项工作。作为建筑系统，我使用了^{}（现在我将使用^{}）。