Python的狮身人面像引用长文件名(Python Sphinx referencing long

我的工作文档（使用狮身人面像和REST）我的Python模块，而且我发现，当交叉引用其他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”之前把空间给它缩进到相同的水平，因为它上面的行输出将包括所有的空间，从而将狮身人面像试图引用类似“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.close引用tarfile.TarFile.close（）函数，即使当前模块未tar文件。由于这样做会变得含糊不清，如果有不止一个可能的匹配，你会得到从狮身人面像的警告。

Answer 2:

您可以使用~前缀，它正是你想要的。

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

Answer 3:

另一种策略是使用REST 替换。这将让你通过调用保存的文本更多的空间:class:交叉引用后面：

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

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

    '''

如果你指的是在许多文件的同一类，可以转而把替代你的狮身人面像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|

    '''

Answer 4:

野生刺在黑暗中。也许这工作：

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

这将是有效的Python

import scipy.\
stats

文章来源: Python Sphinx referencing long names