5

私のドキュメント文字列には、私が定義した他の python クラスへの参照があります。Sphinx がこれらのクラスの 1 つに遭遇するたびに、そのクラスのドキュメントへのリンクを挿入したいと考えています。これはスフィンクスで可能ですか?

具体的には、次のようなドキュメント文字列があります。

'''This class contains a bunch of Foo objects'''

私は書くことができます:

'''This class contains a bunch of :class:`~foo.Foo` objects'''

しかし、Sphinx が一致するすべてのテキストを見つけてFoo、:class: と入力したように見せてくれることを望みます。~foo.Foo

4

2 に答える 2

8

マクロを使用できます。

私のプロジェクトには、すべての「重要な」クラスとグローバル関数、およびそれらの省略形を含むヘッダー ファイルがあります。2 つの例:

.. |PostItem| replace:: :class:`PostItem <hklib.PostItem>`
.. |PostNotFoundError| replace:: :class:`PostNotFoundError <hklib.PostNotFoundError>`

ファイルには、rstこのヘッダー ファイルを含めます。次に、任意のrstファイルでマクロを使用できます。

.. include:: defs.hrst

|PostItem| is a nice class. |PostNotFoundError|, on the other hand is not.

(拡張子を使用して、Python ソース ファイルから docstring を含めることもできますautogen。それらのマクロも同様に置き換えられます。)

あなたの例について:私はFooヘッダーファイルに追加し、このようにdocstringを書きます:

'''This class contains a bunch of |Foo| objects'''
于 2010-03-18T19:01:41.293 に答える
2

Sphinxには、このために解釈されるテキストの役割が多数あります。

https://www.sphinx-doc.org/en/2.0/usage/restructuredtext/domains.html#cross-referencing-python-objects

Fooに入り、Sphinxに:class:を書いたかのように解釈させたいです。~foo.Foo

それは非現実的に聞こえます。テキストを解析しようとするとRSTが麻痺するようです。解釈されたテキストとRSTがサポートするいくつかの引用規則()を探すこと*_|`は、実用的な限界についてです。

あなたが求めていることは、RSTが一日中Foo、すべての可能なコンテキストで各インスタンスをチェックし、リンクが必要かどうかを推論することにつながる可能性があります。Fooこれは、装飾されていない;のインスタンスでのみ必要です。些細な検索と置換は機能しません。

docstringの前処理を台無しにすることができます。

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#docstring-preprocessing

これにより、docstringテキストでグローバルな検索と置換の戦略を試すことができる場合があります。

于 2010-03-18T18:42:07.493 に答える