Sphinx LaTeX标记限制 [英] Sphinx LaTeX markup limitations

问题描述

我正在Sphinx（1.1.2-1版）的多行数学模式里面做三个真正的基本事情。

1. 即使在数学模式下，也可以将下划线作为变量名称的一部分;


2. 使用 \big ， \biggl 等，分隔符做大括号和括号;


3. ，并将常规文本作为方程式的一部分。

请注意以下两件事情。 （1）我使用Python代码中的原始字符串进行Sphinx-markup文档，因此转义字符不需要额外的反斜杠，（2）我没有进行内联数学模式，它在Sphinx中是这样分隔的：

 ：数学：`一些数学的东西去这里`普通的文字可以去这里... 
  

相反，我正在做多行的东西，通常像LaTeX中的 eqnarray

  .. math :: 
 DividendYield& =& \frac {DVT（t）} {CurrentMarketCap} \\ 
 Avg_Assets& =& \biggl（A / B \biggr）\textrm {当B不为零时} 
  

目前，我收到了Sphinx错误（生成的文档页面看起来像乱七八糟的），就像：

 未知LaTeX命令：textrm 
  

同样的情况发生在 \biggl 。对于下划线，它总是将其解释为表示下标，但如果我使用 \textunderscore 或其他技巧，则会抛出与上述相同的错误

数学模式下的下划线， textrm 命令和大分隔符是每个本地TeX包的极其基本的部分我曾经用过那么为什么Sphinx无法访问？

更新

一个特定的Python文件我正在为我计算Book Equity数据。以下，当您看到关于BookEquity的内容时，这是参考。我不能运行我们的构建文档过程，除非通过版本控制系统，所以如果我刚刚修改现有的文件，可以重现的错误是最简单的。

然而，所有我做的是在我的代码中添加以下类函数，使用简单的docstring。

  def foo（self）：
r
示例docstring 
 
 .. math :: 
 Ax& =& b \\ 
 Cx& =& \\ biggl（\frac {x / y} \biggr）\textrm {如果y不为零} 

 pass 
  / pre> 
 
 
然后，下面的图像是使用Sphinx 1.1.2-1构建文档的输出。
 
 
 
  
 
 
 
如果您右键单击并选择查看图像，您可以看到更好的版本。
解决方案
你必须编辑 sphinx-quickstart 创建的标准配置文件，否则sphinx将在数学块中barf。在文件 conf.py 中，我更改了
  extensions = [] 
  
至
  extensions = ['sphinx.ext.pngmath'] 
  
之后，以下rst文件更多或更少的工作; 
  .. foo文档主文件，由
 sphinx-quickstart在Thu Oct创建25 11:04:31 2012. 
您可以将此文件完全适应您的喜好，但应至少
包含根toctree指令。 
 
欢迎来到foo的文档！ 
 ============================= 
 
内容：
 
 .. toctree :: 
：maxdepth：2 
 
这是第一章
 =============== ======== 
 
相反，我正在做多行的东西，经常像LaTeX中的eqnarray一样：
 
 .. math :: 
 DividendYield &安培; =&安培; \frac {DVT（t）} {CurrentMarketCap} \\ 
 Avg_Assets& =& \biggl（A / B \biggr）\textrm {当B不为零时} 
  
它为数学片段生成了以下LaTeX代码：
  \chapter {这是第一章} 
 \label {index：welcome-to-foo-s-documentation} \label {index：this-is-the-first-chapter} 
相反，我正在做多行内容，通常就像LaTeX中的eqnarray：
 \begin {gather} 
 \begin {split} DividendYield& =& \frac {DVT（t）} {CurrentMarketCap} \\ 
 Avg_Assets& =& \biggl（A / B \biggr）\textrm {当B不为零时} \end {split} \\\
otag\\\begin {split} \end {split} \\ \\ notag 
 \end {gather} 
  
选择使用split和收集对我来说似乎有点奇怪，显然对于您为eqnarray编写的代码并不能很好的工作，但是这在Sphinx中是硬编码的。
 
 
 
运行pdflatex停止 \end {gather} ，错误额外的对齐标签已更改为\cr。但我是能够通过输入不间断模式继续过去。这给我以下结果：
 
 
 
  
 
 
 
虽然对齐还是有问题（因为 split 和<$ c $之间的区别c> eqnarray 环境），textrm和biggl似乎工作正常。 （请注意，您仍然必须在 Average_Assets 中转义下划线，但这是AFAICT课程的标准。
 
 
 
您可以通过后处理生成的LaTeX代码，例如通过替换 \begin {gather} \begin {split} 和 \end {split} \\\
otag\\\begin {split} \end {split} \\\
otag\end {gather} 由您选择的数学环境。
 
 
 
 更新：
 
 
 
更新的截图似乎来自网页，而不是LaTeX文档！所以看起来我发现导致错误的是处理器，它将LaTeX数学符号转换成浏览器可以显示的内容。这可能是 MathJax 或 jsMath 。从代码看， pngmath 将产生其他错误消息。根据此页面，您的代码段应该工作mathjax。从 jsMath符号页面，它看起来不像jsmath一样支持 \Biggl 。所以我最好的猜测是SPhinx被配置为使用jsMath。看看生成的网页的来源应该告诉你用来渲染数学的东西。如果我的猜测是正确的，切换配置以使用mathjax并稍微调整您的方程式可能会解决问题。
 
 
 
  Update2 ：我可以肯定地确认它可以用MathJax工作正常（见下文）。我没有安装jsMath。
 
 
 
  
 
I'm trying to do three really basic things inside of a multi-line math mode in Sphinx (version 1.1.2-1).

Write underscores as part of my variable names even in math mode;
Use the \big, \biggl, etc., delimiters to make large brackets and parentheses;
and include regular text as part of equations.
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...
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...}
Currently, I get Sphinx errors (and the generated doc pages look like gibberish), that say things like: 
Unknown LaTeX command: textrm
The same happens for \biggl. For the underscore, it just always interprets it as if I am denoting a subscript, but if I use \textunderscore or other tricks then it throws the same sorts of errors as above.

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?

Update

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 &=& \biggl(\frac{x/y}\biggr) \textrm{ if y is not zero.}
    """
    pass
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.
解决方案
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 = []
to
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 &=& \biggl( A/B \biggr) \textrm { when B is not zero...}
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:
\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}
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.

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:



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

You might get away with postprocessing the generated LaTeX code, e.g. by replacing \begin{gather}\begin{split} and \end{split}\notag\\\begin{split}\end{split}\notag\end{gather} by the math environment of your choice.

Update:

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: I can definitely confirm that it works fine with MathJax (see below). I don't have jsMath installed, though.



                        
这篇关于Sphinx LaTeX标记限制的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！