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错误(生成的doc页面看起来像乱码),这些说法如下:

Unknown LaTeX command: textrm

同样的事情发生了\biggl.对于下划线,它总是将其解释为我表示下标,但如果我使用\textunderscore或其他技巧,那么它会抛出与上面相同类型的错误.

数学模式下的下划线,textrm命令和大分隔符是我曾经使用的每个本机TeX包的极其基本的部分.那么为什么通过Sphinx无法进入？

更新

我正在处理的一个特定Python文件为我计算了Book Equity数据.所以下面,当你看到关于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将在数学块中进行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将产生其他错误消息.根据此页面,您的代码段应该在mathjax中工作.从jsMath符号页面看,它看起来不像jsmath支持\Biggl.所以我最好的猜测是SPhinx配置为使用jsMath.查看生成的网页的来源应该告诉您用于渲染数学的内容.如果我的猜测是正确的,切换配置以使用mathjax并稍微调整您的等式可能会解决问题.

Update2:我绝对可以确认它与MathJax一起工作正常(见下文).但是,我没有安装jsMath.

Answer 2

更新

如上所述,sphinx使用gather和split数学模式.根据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问题.

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

原始答案

Sphinx生产"不寻常"的乳胶代码.它使用gather和split用于方程式(看看它产生的乳胶源).

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

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

我想我还记得一些关于这个主题的开发人员的批评:docutils有一个乳胶构建器(似乎"更好"),但sphinx不使用这个构建器.

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

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

我改编了sphinx Makefile,只需一步即可完成.作为我使用的建筑系统rubber(现在我会使用latexmk).