長い名前を参照するPython Sphinx

Question

私は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のドキュメントはスフィンクスが完全に名前のバージョンで短縮バージョンを関連付けることができない完全なパス名に結びついていると考えています。

ご協力いただきますようお願い申し上げます。

編集2012年4月5日：

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

そして、これが正常に働いていた：

j13rの答え/提案を1として（下記参照）私は、次のことを試してみました。これを動作させるための唯一の注意点は、2行目にスペースを入れてはいけないということです（ドキュメントストリングでこれを使用するとかなり不快です）。したがって、私の元の例を動作させると、次のようになります。

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

    ''' 

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

私も、私は動作しませんでした。この二つの他のバリエーション、試したことに注意してください：私はドキュメンテーション文字列の書式設定を破壊伴わない解決策を探していました

# 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` 

を、私が思いますそれは...私は実際にこれに80文字を超える行を好むと思う。

答えがj13rのおかげです！

Answer 1

スフィンクスのドキュメント（http://sphinx.pocoo.org/domains.html?highlight=current#cross-referencing-python-objects）によると、あなたのターゲットクラスの前にドットを使用することができます有効なPythonのようになります。

:class:`.ReallyLongExampleClassName` 

または

:class:`.module5.ReallyLongExampleClassName` 

とクラスのスフィンクス検索してみましょう：名前はドットで始まっている、と正確に一致するものが存在していない場合

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

Answer 2

暗闇で野生の刺す。おそらく、これは動作します：

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

それは

import scipy.\ 
stats 

Answer 3

~を接頭辞として使用できます。これはまさにあなたが望むものです。

http://sphinx-doc.org/markup/inline.html#xref-syntax

Answer 4

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

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

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

    ''' 

あなたがあなたのファイルの多くで同じクラスに言及している場合は、代わりに自分の中での置換を入れることができますSphinx conf.pyファイルのrst_epilog設定を使用します。

rst_epilog

読まれているすべてのソースファイルの末尾に含まれるreStructuredTextの文字列：Sphinxのドキュメントから。これは、すべてのファイルで使用できる置換を追加する適切な場所です。例：

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

バージョン0.6の新機能

次に、あなたのドキュメント文字列だけで次のようになります。提案のための

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

    '''