web-dev-qa-db-ja.com

numpy、scipy、matplotlibへのsphinx間リンクのターゲットを指定する

パッケージ間のSphinxドキュメントリンクを設定するためのドキュメントに従って、私は追加しました

intersphinx_mapping = {'python': ('http://docs.python.org/2', None),
                       'numpy': ('http://docs.scipy.org/doc/numpy/', None),
                       'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
                       'matplotlib': ('http://matplotlib.sourceforge.net/', None)}

私のconf.pyにアクセスしましたが、Python自体が機能する以外のプロジェクトへのリンクを取得できないようです。たとえば、

:term:`svg graphics <matplotlib:svg>`

予想される#term-svgアンカーを追加せずに、インデックスページに移動するだけで、scipyの用語集を見つけられなかったり、パッケージでサポートされている:ref:sまたは:term:sを特定したりできません。

numpy、scipy、およびmatplotlibで:ref:sおよび:term:sのターゲットを指定する方法の説明はどこにありますか？

さらに言えば、Sphinx自体にリンクするにはどうすればよいですか？追加

intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', None)

そして

:ref:`Intersphinx <intersphinx>`

動作しません。

pythonnumpymatplotlibscipypython-sphinx
65
orome

numpy、scipy、およびmatplotlibで_:ref:_ sおよび_:term:_ sのターゲットを指定する方法の説明はどこにありますか？

Gist に、いくつかのintersphinxマッピングがあり、これにはnumpy、scipy、およびmatplotlibのすべてが含まれています。これらのエントリは、_intersphinx_mapping_内の _conf.py_ で直接使用できるはずです。このリストに追加するエントリの提案がある場合は、Gistのコメントにリクエストを投稿してください。

これらすべてのパッケージについて、 fgoudraの回答 ごとに sphobjinv を使用して各ライブラリの_objects.inv_ファイル内を検索することを強くお勧めします。 （完全な開示：私はsphobjinvの作成者です。）CLIインターフェースの suggest モードは、intersphinx相互参照を構成するために必要な情報を提供するように特別に設計されています。

numpyは複雑です。完全修飾名が必要な場合があります。例：

_:func:`numpy.cross`
_

また、（たとえばC関数の場合）関数のベース名を参照することもできますが、ドメインを明示的に指定する必要があります。例：

_:c:func:`PyArray_InnerProduct`
_

さらに、カスタムnpドメインを参照する必要がある場合もあります。例：

_:np:func:`numpy.ma.append`
_

_objects.inv_を調べなければ、正しい構文を知る方法はありません。

scipyは、おおよそnumpyと同じくらいわかりにくいです。さまざまなカスタムドメインが多数導入されているため、状況はさらに複雑になっています。 scipyサブパッケージ、例：

_:scipy-optimize:func:`scipy.integrate.newton_cotes`
_

matplotlib、の場合、参照で（非常に詳細な）完全に指定されたオブジェクト名を常に指定する必要があるようです。例：

_:meth:`matplotlib.axes.Axes.plot`
_

すべてのmatplotlibコードオブジェクトはデフォルトのpyドメインにあるように見えますが、これにより多少単純化されます。

これらのいずれについても、リンクを正しく構築するのに問題がある場合、最初にフォールバックするのは、一般的な_:obj:_役割、例：

_:obj:`matplotlib.axes.Axes.plot`
_

これにより、特定のオブジェクトが定義された役割に関係なく、intersphinxリンクが構築されますが、関連するデフォルト以外のドメインを正しく指定する必要があると思います。参照が_:obj:_ロールで正しく機能しない場合は、オブジェクト名またはドメインのどこかにエラーがあります。両方の場所でタイプミスを確認してください。

9
hBy2Py

確認するインベントリを手動で指定することができます。たとえば、intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', None)が機能しない場合は、いつでもインベントリをダウンロードし、手動でマッピングに追加できます（例： http://sphinx-doc.orgからダウンロード） /objects.inv 、バイナリファイルをドキュメントに保存し、マッピングにパスを追加します。これにより、次のようになります。

intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', ('objects.inv', ), )

インベントリ内に参照が存在するかどうかを確認するには、 sphobjinv pythonパッケージを使用してバイナリを探索し、場所を確認します必要なリファレンスです。

これは問題の解決策ではないかもしれませんが、いくつかのことをデバッグするのに役立ちます。

4
fgoudra

これがまだ問題である場合は、URLの末尾のスラッシュを省略する必要があります。

intersphinx_mapping = {'python': ('http://docs.python.org/2', None),
                       'numpy': ('http://docs.scipy.org/doc/numpy', None),
                       'scipy': ('http://docs.scipy.org/doc/scipy/reference', None),
                       'matplotlib': ('http://matplotlib.sourceforge.net', None)}
2
John Truckenbrodt

相互参照を行う方法を知るための追加の方法は、 sphobjinv モジュールを使用することです。

ローカルまたはリモートのインベントリファイルを検索できます（あいまい一致を使用）。たとえばscipyの場合：

$ sphobjinv suggest -t 90 -u https://docs.scipy.org/doc/scipy/reference/objects.inv "signal.convolve2d"

Remote inventory found.

:py:function:`scipy.signal.convolve2d`
:std:doc:`generated/scipy.signal.convolve2d`

:py:func:ではなく:py:function:を使用する必要がある場合があることに注意してください（理由を知っていただければ幸いです）。

1
Francis Colas