python - Sphinx LaTeX マークアップの制限事項

Question

Sphinx (バージョン 1.1.2-1) の複数行の数学モード内で、3 つの非常に基本的なことを実行しようとしています。

1. 数学モードでも、変数名の一部としてアンダースコアを書きます。
2. \big、などの区切り文字を使用して、\biggl大きな括弧と括弧を作成します。
3. 数式の一部として通常のテキストを含めます。

以下の 2 点に注意してください。(1) Sphinx マークアップ ドキュメントの Python コードで生の文字列を使用しているため、エスケープ文字に余分なバックスラッシュは必要ありません。(2) インライン数学モードを使用していません。これは Sphinx で次のように区切られています。

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

代わりに、eqnarrayLaTeX のように、複数行の処理を行っています。

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

現在、次のような Sphinx エラーが発生します (そして、生成されたドキュメント ページは意味不明のように見えます)。

Unknown LaTeX command: textrm

同じことが起こり\bigglます。アンダースコアの場合、常に下付き文字を示しているかのように解釈しますが、\textunderscoreまたは他のトリックを使用すると、上記と同じ種類のエラーがスローされます。

数学モード内のアンダースコア、textrmコマンド、および大きな区切り文字は、私が今まで使用したすべてのネイティブ TeX パッケージの非常に基本的な部分です。では、なぜ Sphinx からアクセスできないのでしょうか?

アップデート

私が取り組んでいる特定の Python ファイルの 1 つで、Book Equity データが計算されます。以下、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 が数学ブロックでバーフします。ファイル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}

分割と収集の組み合わせを使用するという選択は、私には少し奇妙に思えます。また、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}

更新：

アップデートのスクリーンショットは、LaTeX ドキュメントではなく、ウェブページのもののようです! したがって、エラーを生成しているのは、LaTeX 数学表記を変換してブラウザーが表示できるようにするハンドラーであるように見えます。それはおそらく または のいずれMathJaxかになりますjsMath。コードを見ると、pngmath他のエラー メッセージが生成されます。このページによると、コード スニペットはmathjax で動作するはずです。jsMathシンボル ページから、jsmath がサポートしているようには見えません。\Biggl. したがって、SPhinx は jsMath を使用するように構成されていると思います。生成された Web ページのソースを確認すると、数学のレンダリングに何が使用されているかがわかります。私の推測が正しければ、構成を mathjax を使用するように切り替えて、式を少し調整すると問題が解決する可能性があります。

Update2 : MathJax で問題なく動作することは間違いなく確認できます (以下を参照)。ただし、jsMath はインストールしていません。

Answer 2

アップデート

前述のように、sphinx は数学モードにgatherandを使用します。AMS 数学ガイドsplitによると、分割には単一の符号が必要です。そう$

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

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

元の答え

Sphinx は「異常な」ラテックス コードを生成します。方程式にgatherandを使用します (生成されるラテックス ソースを見てください)。split

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

Sphinx は html ドキュメント用に設計されており (Web 開発者によるものだと思います)、ラテックス (および番号付きの図、表、方程式などの科学的な「問題」) は、このプロジェクトの主な焦点ではないようです。ところで、コードは mathjax 拡張機能を使用して html に正しくレンダリングされます。

このトピックに関する docutils 開発者による批判も覚えていると思います。

sphinx で作成されたラテックス コードを後処理するrelatex(リンク)というプロジェクトがメーリング リストで発表されたことがあります。しかし、開発状況についてはよくわかりません。ここで公開した独自のコードを使用しました(残念ながら、ドイツ語と英語が混在しています)。スフィンクスラテックスの後処理が複雑すぎると判断し、純粋なラテックスに切り替えたため、あまり役に立たないと思います。だから私はそれをさらに開発しませんでした。ただし、基本的な手順は

• 独自のラテックス スタイルとテンプレートを作成します。
• Sphinx にラテックス コードを作成させます
• ラテックスコードを後処理してテンプレートに貼り付けます
• LaTeX の構築システムを使用して、コードから pdf を生成します

これを 1 つのステップで実行できるように、sphinx の Makefile を調整しました。私が使用した建物システムとしてrubber（最近は を使用しますlatexmk）。