Sphinx LaTeXのマークアップの制限

Question

私は、Sphinx（バージョン1.1.2-1）の複数行の数学モードの中で、3つの本当に基本的なことをやろうとしています。

1. 数値モードでも変数名の一部として下線を書きます。
2. \big、\bigglなどの区切り記号を使用して大括弧とかっこを作成します。
3. であり、方程式の一部として通常のテキストを含みます。

次の2点に注意してください。 （1）私はPythonコードでSphinx-Markupドキュメントの生の文字列を使用していますので、余分なバックスラッシュはエスケープ文字には必要ありません。（2）Sphinxでこのように区切られたインライン演算モードは使用しません。物事を言う

.. math:: 
    DividendYield &=& \frac{DVT(t)}{CurrentMarketCap} \\ 
    Avg_Assets &=& \biggl(A/B \biggr) \textrm { when B is not zero...} 

現在、私はスフィンクスのエラーが出る（および生成されたドキュメントのページはちんぷんかんぷんのように見える）、：

:math:`Some math stuff goes here` regular text could go here... 

代わりに、私は、複数行のものをやっていることが多いのLaTeXでeqnarrayが好きlike：

Unknown LaTeX command: textrm 

\bigglについても同様です。下線の場合、それはちょうど私が下付き文字を表しているかのように解釈しますが、\textunderscoreまたは他のトリックを使用すると、上記と同じ種類のエラーがスローされます。

数値モードの下線、textrmコマンド、および大きな区切り文字は、これまで使用してきたすべてのネイティブTeXパッケージの極めて基本的な部分です。だから、なぜ彼らはスフィンクスを通してアクセスできないのですか？私が働いている

更新

一つの特定のPythonのファイルは私のためにブックエクイティデータを算出します。下に、BookEquityについての情報が表示されたら、これが参考になります。バージョン管理システムを除いてbuild-docsプロセスを実行することはできないので、既存のファイルを変更しただけで再現性のあるエラーを作成するのが最も簡単でした。

しかし、私がしたのは、コード内に次のクラス関数を単純な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

sphinx-quickstartが作成する標準設定ファイルを編集する必要があります。それ以外の場合、sphinxはmathブロックでbarfします。下記の最初のファイル多かれ少なかれが働いた後、ファイルconf.pyでは、私は

extensions = ['sphinx.ext.pngmath'] 

に

extensions = [] 

を変えました。

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

分割の組み合わせを使用しての選択をし、収集は、私には少し奇妙なようだ、と明らかにしてうまく動作しません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}を任意の数学環境で置き換えます。

更新：

更新からのスクリーンショットは、Webページではなく、LaTeX文書からのようです！だから、エラーを生成しているのは、LaTeXの数式表記をブラウザが表示できるように変換するハンドラです。おそらくMathJaxまたはjsMathのいずれかになります。コードを見ると、pngmathは他のエラーメッセージを生成します。 this pageによると、コードスニペットははmathjaxで動作するはずです。 jsMath symbols pageから、jsmathが\Bigglをサポートしているように見えません。ですから、私の推測では、SPhinxはjsMathを使用するように設定されています。生成されたWebページのソースを覗いて、数学を表現するために使用されるものを教えてください。私の推測が正しい場合は、構成を切り替えてmathjaxを使用し、方程式を少し修正すると問題が解決する可能性があります。

更新2：MathJax（下記参照）でうまく動作することは間違いありません。私はjsMathをインストールしていない。

Answer 2

更新

述べたように、スフィンクスは、数式モードのためgatherとsplitを使用しています。 AMS math guideによると、分割は1つで$となります。だから、

def foo(self): 
    r"""Sample docstring 

    .. math:: 
     Ax &= b \\ 
     Cx &= \biggl(\frac{x}{y} \biggr) \textrm{ if y is not zero.} 
    """ 
    pass 

として定義fooで

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

はlatexpdfと罰金レンダリングし、MathJax extensionをHTMLに。

私が働いていた数式モードでのアンダースコアのため\_を使用しますが、\textunderscoreは動作しませんでした。注（あなたがtex.stackexchange.comにthis questionを参照してください、私は考えて追加パッケージをロードする必要があります）。 あなたの質問は明らかにTexの質問と思います。

以前の回答は削除しませんが、htmlビルダーではなく、ラテックスビルダーにのみ適用されます。

オリジナル答え

スフィンクスは "珍しい" ラテックスコードを生成します。方程式にはgatherとsplitが使われます（生成するラテックスソースを見てください）。

問題は、生成するラテックスソースを変更する簡単な方法がないことです。 「科学的」グレードのラテックスコードを取得するには、ラテックスソースを後処理する必要があります。

スフィンクスはhtmlドキュメント用に設計されていますが、ラテックス（番号付きの図、表、方程式などの科学的な「問題」）はプロジェクトの主な焦点ではないようです。ちなみに、あなたのコードはmathjax拡張機能でhtmlにうまく描画されます。

docutilsにはラテックスビルダー（「より良い」と思われる）がありますが、このビルダーはsphinxでは使用されていません。

メーリングリストにrelatex（link）と呼ばれるプロジェクトの発表がありました。これは、sphinxで作成されたラテックスコードを後処理するためのものです。しかし、私は開発状況については分かりません。 自分でコードを使用しましたが、これはhere（残念ながらドイツ語と英語の混合物）です。私はそれが非常に便利だとは思わない、私はそれが後処理スフィンクスラテックスに複雑にすることを決めたので、私は純粋なラテックスに切り替えた。だから私はそれをさらに発展させませんでした。しかし

独自のラテックスのスタイルとテンプレートを

• を作成している基本的な手順は、スフィンクスがために構築システムを使用し、それはラテックスコード
• 後処理ラテックスコードだ作成して、テンプレート
• に貼り付けてみましょうLaTeXがあなたのコードからpdfを生成する

私は、これを一度に行うためにsphinx Makefileを採用しました。私はrubber（最近は私はlatexmkを使用する）を使用して構築システムとして。

Answer 3

は今（2016）スフィンクスの数学のディレクティブは、そうするユーザーにフルコントロールを返すオプション:nowrap:を、持っているだけで

.. math:: 
    :nowrap: 

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

htmlとlatexpdfの両方で細かいレンダリングします。