Sphinx LaTeX 标记限制
问题描述
我正在尝试在 Sphinx(版本 1.1.2-1)的多线数学模式中做三件非常基本的事情.
I'm trying to do three really basic things inside of a multi-line math mode in Sphinx (version 1.1.2-1).
- 即使在数学模式下，也将下划线作为我的变量名的一部分；
- 使用
ig、iggl等分隔符制作大括号和圆括号； - 并将常规文本作为方程式的一部分.
- Write underscores as part of my variable names even in math mode;
- Use the
ig,iggl, etc., delimiters to make large brackets and parentheses; - and include regular text as part of equations.
注意以下两点.(1) 我在我的 Python 代码中为 Sphinx 标记文档使用了原始字符串，因此转义字符不需要额外的反斜杠，并且 (2) 我没有使用内联数学模式，它在 Sphinx 中是这样分隔的:
Note the following two things. (1) I am using a raw string in my Python code for the Sphinx-markup documentation, so extra backslashes are not needed for escape characters, and (2) I am not doing inline math mode, which is delimited like this in Sphinx:
:math:`Some math stuff goes here` regular text could go here...
相反，我正在做多行的东西，通常像 LaTeX 中的 eqnarray:
Instead, I am doing multi-line stuff, often like eqnarray in LaTeX:
.. math::
DividendYield &=& frac{DVT(t)}{CurrentMarketCap} \
Avg_Assets &=& iggl( A/B iggr) extrm { when B is not zero...}
目前，我收到 Sphinx 错误(生成的文档页面看起来像乱码)，说的是:
Currently, I get Sphinx errors (and the generated doc pages look like gibberish), that say things like:
Unknown LaTeX command: textrm
iggl 也是如此.对于下划线，它总是将其解释为好像我表示下标一样，但如果我使用 extunderscore 或其他技巧，则会引发与上述相同的错误.
The same happens for iggl. For the underscore, it just always interprets it as if I am denoting a subscript, but if I use extunderscore or other tricks then it throws the same sorts of errors as above.
数学模式中的下划线、textrm 命令和大分隔符是我曾经使用过的每个本机 TeX 包的非常基本的部分.那么为什么它们无法通过 Sphinx 访问呢?
Underscores within math mode, the textrm command, and big delimiters are extremely basic parts of every native TeX package I've ever used. So why are they inaccessible through Sphinx?
更新
我正在处理的一个特定 Python 文件为我计算账面净值数据.所以下面，当你看到关于 BookEquity 的东西时，这就是参考.除非通过版本控制系统，否则我无法运行我们的构建文档流程，因此如果我只是修改现有文件，则最容易出现可重现的错误.
One particular Python file that I am working on calculates Book Equity data for me. So below, when you see the stuff about BookEquity, that's the reference. I can't run our build-docs process except through a version control system, so making a reproducible error was easiest if I just modified an existing file.
然而，我所做的只是在我的代码中添加以下类函数，并带有一个简单的文档字符串.
However, all I did was to add the following class function in my code, with a simple docstring.
def foo(self):
r"""
Sample docstring
.. math::
Ax &=& b \
Cx &=& iggl(frac{x/y}iggr) extrm{ if y is not zero.}
"""
pass
然后下图是使用 Sphinx 1.1.2-1 构建文档的输出.
And then the image below is the output coming from building the docs with Sphinx 1.1.2-1.
如果您右键单击并选择查看图像"，您可以看到更好的版本.
If you right-click and select 'view image' you can see a better version.
解决方案
你必须编辑 sphinx-quickstart 创建的标准配置文件，否则 sphinx 会在数学块上出错.在文件 conf.py 中，我改变了
You have to edit the standard configuration file that sphinx-quickstart creates, otherwise sphinx will barf at math blocks. In the file conf.py, I changed
extensions = []
到
extensions = ['sphinx.ext.pngmath']
之后，以下第一个文件或多或少起作用了；
After that the following rst file more-or-less worked;
.. 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 &=& iggl( A/B iggr) extrm { when B is not zero...}
它为数学片段生成了以下 LaTeX 代码:
It produced the following LaTeX code for the math fragment:
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:
egin{gather}
egin{split}DividendYield &=& frac{DVT(t)}{CurrentMarketCap} \
Avg_Assets &=& iggl( A/B iggr) extrm { when B is not zero...}end{split}
otag\egin{split}end{split}
otag
end{gather}
使用 split 和 gather 组合的选择对我来说似乎有点奇怪，而且显然不适用于您为 eqnarray 编写的代码，但这在 Sphinx 中是硬编码的.
The choice of using the combination of split and gather seems a bit weird to me, and obviously doesn't work well with the code you wrote for eqnarray, but this is hardcoded in Sphinx.
运行 pdflatex 确实在 end{gather} 处停止，错误 Extra alignment tab has been changed to cr. 但我能够通过进入不间断模式.这给了我以下结果:
Running pdflatex did stop at end{gather}, with the error Extra alignment tab has been changed to cr. but I was able to proceed past that by entering nonstopmode. This give me the following result:
虽然对齐仍然有问题(由于 split 和 eqnarray 环境之间的差异)，但 textrm 和 biggl 似乎工作正常.(请注意，您仍然必须转义 Average_Assets 中的下划线，但这是课程的标准，AFAICT).
While there is still something wrong with the alignment (because of the differences between the split and eqnarray environments), the textrm and biggl seem to work fine. (Note that you'll still have to escape the underscore in Average_Assets, but that is par for the course, AFAICT).
您可能可以对生成的 LaTeX 代码进行后处理，例如通过替换 egin{gather}egin{split} 和 end{split}
otag\egin{split}end{split}
otagend{gather} 由您选择的数学环境决定.
You might get away with postprocessing the generated LaTeX code, e.g. by replacing egin{gather}egin{split} and end{split}
otag\egin{split}end{split}
otagend{gather} by the math environment of your choice.
更新:
更新的屏幕截图似乎来自网页，而不是 LaTeX 文档！所以在我看来，产生错误的是处理程序，它转换了 LaTeX 数学符号，以便浏览器可以显示.那可能是 MathJax 或 jsMath.通过查看代码，pngmath 会产生其他错误消息.根据 this page，您的代码片段应该在数学贾克斯.从 jsMath 符号页面，它看起来不像像 jsmath 支持 Biggl.所以我最好的猜测是 SPhinx 被配置为使用 jsMath.查看生成的网页的来源应该会告诉您用于呈现数学的内容.如果我的猜测是正确的，将配置切换为使用 mathjax 并稍微调整您的方程式可能会解决问题.
The screenshot from the update seems to be from a webpage, not a LaTeX document! So it looks to me that what is producing the error is the handler that converts the LaTeX math notation so something a browser can show. That will be probably be either MathJax or jsMath. From looking at the code, pngmath would produce other error messages. According to this page, your code snippet should work in mathjax. From the jsMath symbols page, it doesn't look like jsmath supports Biggl. So my best guess is that SPhinx is configured to use jsMath. A peek at the source of the generated web page should tell you what is used to render the math. If my guess is correct, switching the configuration to use mathjax and slightly adapting your equation might fix the problem.
Update2:我可以肯定地确认它在 MathJax 上运行良好(见下文).不过，我没有安装 jsMath.
Update2: I can definitely confirm that it works fine with MathJax (see below). I don't have jsMath installed, though.
相关文章