引用長名稱的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的文檔被綁定到該獅身人面像不能完全命名版本的縮短版相關的完整路徑名。

任何幫助將不勝感激。

編輯04/05/2012：

按照j13r的答案/建議（見下文），我試過如下：

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

而這種成功合作。唯一需要注意的是，第二行必須沒有空格（在文檔字符串中使用它時非常令人沮喪）。因此，使我的原始示例工作，它看起來像：

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），你可以在你的目標上課前使用圓點：

:class:`.ReallyLongExampleClassName` 

或

:class:`.module5.ReallyLongExampleClassName` 

，讓該類獅身人面像搜索：

...如果該名稱的前綴以一個點，並沒有發現完全匹配，目標被作爲後綴，並與後綴的所有對象名稱進行搜索。例如，即使當前模塊不是tarfile，py：meth：.TarFile.close也引用了tarfile.TarFile.close（）函數。由於這可能不明確，如果有多個可能的匹配，你會從Sphinx得到警告。

Answer 2

野生刺在黑暗中。也許這個作品：

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

這將是有效的Python

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

新結構化的字符串將包含在所讀出每一個源文件的末尾。這是添加應該在每個文件中可用的替代品的正確位置。舉例：

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

版本0.6中的新功能。

那麼你的文檔字符串也只是：

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

    '''