15

私はPythonモジュールのドキュメントに取り組んでいます（SphinxとreSTを使用）。他のPythonオブジェクト（モジュール、クラス、関数など）を相互参照すると、完全なオブジェクト名が非常に長くなることがわかりました。多くの場合、80文字を超えるので、絶対に避けたいと思います。

次に例を示します。

def exampleFunction():
    '''Here is an example docstring referencing another
    :class:`module1.module2.module3.module4.module5.ReallyLongExampleClassName`

    '''

問題は、ReallyLongExampleClassNameクラスのドキュメントを作成するときに、フルパス名用にドキュメントを生成したことですmodule1.module2.module3.module4.module5.ReallyLongExampleClassaName。

これを解決する方法はありますか？私は次の方法を試しましたが、成功しませんでした。

1）モジュール名の途中に改行を追加します。例：

:class:`module1.module2.module3.module4.
module5.ReallyLongExampleClassName`

2）別の（ただしPythonでインポート可能な）方法でクラス名を参照する。例：

:class:`module1.module2.ReallyLongClassName`

のドキュメントReallyLongClassNameはフルパス名に関連付けられているため、Sphinxは短縮バージョンを完全な名前のバージョンと関連付けることができないと思います。


2012年4月5日編集：

j13rの回答/提案（以下を参照）に従って、私は次のことを試みました：

:class:`module1.module2.module3.module4.module5\
ReallyLongExampleClassName`

そして、これはうまくいきました。これを機能させるための唯一の注意点は、2行目の前にスペースを入れてはならないということです（これをdocstringで使用する場合は非常にイライラします）。したがって、元の例を機能させるには、次のようになります。

def exampleFunction():
    '''Here is an example docstring referencing another
    :class:`module1.module2.module3.module4.module5.\
ReallyLongExampleClassName`

    '''

いい、そして醜い。ReallyLongExampleClassNameその上の行と同じレベルにインデントする前にスペースを入れると、出力にはスペースが含まれるため、Sphinxは。のようなものを参照しようとしますmodule1.module2.module3.module4.module5.ReallyLongExampleClassName。

また、これの他の2つのバリエーションを試しましたが、機能しませんでした。

    # Note: Trying to put a space before the '\'
    :class:`module1.module2.module3.module4.module5. \
ReallyLongExampleClassName`

    # Note: Trying to leave out the '\'
    :class:`module1.module2.module3.module4.module5.
ReallyLongExampleClassName`

docstringのフォーマットを破壊しない解決策を探していましたが、それでうまくいくと思います...実際には、これよりも80文字を超える行の方が好きだと思います。

答えてくれたj13rに感謝します！

4

4 に答える 4

21

sphinxのドキュメント（https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects）によると、ターゲットクラスの前にドットを使用できます。

:class:`.ReallyLongExampleClassName`

また

:class:`.module5.ReallyLongExampleClassName`

そして、sphinxにクラスを検索させます。

...名前の前にドットが付いていて、完全に一致するものが見つからない場合、ターゲットはサフィックスと見なされ、そのサフィックスを持つすべてのオブジェクト名が検索されます。たとえば、：py：meth：.TarFile.closeは、現在のモジュールがtarfileでない場合でも、tarfile.TarFile.close（）関数を参照します。これはあいまいになる可能性があるため、一致する可能性のあるものが複数ある場合は、Sphinxから警告が表示されます。

于 2012-04-08T21:43:40.670 に答える
2

別の戦略は、 reST Substitutionsを使用することです。:class:これにより、後で相互参照を呼び出すことで、テキストのスペースを節約できます。

def exampleFunction():
    '''Here is an example docstring referencing another
    |ReallyLongExampleClassName|

    .. |ReallyLongExampleClassName| replace:: 
                                    :class:`.ReallyLongExampleClassName`

    '''

多くのファイルで同じクラスを参照している場合は、代わりにrst_epilog設定を使用して、Sphinx conf.py ファイルに置換を入れることができます。スフィンクスのドキュメントから：

rst_epilog

読み取られるすべてのソース ファイルの末尾に含まれる reStructuredText の文字列。これは、すべてのファイルで使用できる置換を追加するのに適した場所です。例：

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

バージョン 0.6 で追加。

次に、docstringは次のようになります。

def exampleFunction():
    '''Here is an example docstring referencing another
    |ReallyLongExampleClassName|

    '''
于 2016-02-03T02:28:33.897 に答える
1

暗闇の中で野生の刺し傷。おそらくこれは機能します：

:class:`module1.module2.module3.module4.\
module5.ReallyLongExampleClassName`

有効なPythonになります

import scipy.\
stats
于 2012-04-05T22:06:35.557 に答える