使用Python Sphinx引用长名称

我正在为我的Python模块编写文档（使用Sphinx和reST），我发现当交叉引用其他Python对象（模块、类、函数等）时，对象的完整名称最终会非常长。它通常超过80个字符，这是我愿意不惜一切代价避免的

以下是一个例子：

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

    '''

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

问题是，在为ReallyLongExampleClassName类创建文档时，我为完整路径名

module1.module2.module3.module4.module5.ReallyLongExampleClassName

生成了文档

我想知道有没有办法解决这个问题？我尝试过以下方法，但没有成功：

< P> 1）在模块名中间添加一个断线。例如：

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

:class:`module1.module2.ReallyLongClassName`

2） 以不同的（但仍然是可导入的）方式引用类名。例如：

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

:class:`module1.module2.ReallyLongClassName`

我认为，由于

ReallyLongClassName

的文档与完整路径名相关联，因此Sphinx无法将缩短版本与完整命名版本相关联

编辑2012年5月4日：

根据j13r的回答/建议（见下文），我尝试了以下方法：

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

这是成功的。要让它工作，唯一需要注意的是第二行前面不能有空格（在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

的内容

我还应该指出，我尝试了其他两种变体，但都不起作用：

    # 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的回答

黑暗中的疯狂刺杀。也许这是可行的：

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

这将是有效的

import scipy.\
stats

---

根据sphinx文档（），您可以在目标类之前使用点：

:class:`.ReallyLongExampleClassName`

或

让斯芬克斯搜索这个类：

。。。如果名称以点作为前缀，但未找到精确匹配，则将目标作为后缀，并搜索具有该后缀的所有对象名称。例如，：py:meth:

.TarFile.close

引用TarFile.TarFile.close（）函数，即使当前模块不是TarFile。由于这可能会变得模棱两可，如果存在多个可能的匹配项，您将从Sphinx收到警告

---

您可以使用

~

作为前缀，它完全满足您的需要

---

另一个策略是使用reST。这将允许您稍后通过调用

：class:

交叉引用在文本中节省更多空间：

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

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

    '''

如果在许多文件中引用同一个类，可以使用设置将替换放在Sphinx conf.py文件中。从Sphinx文档中：

rst\U尾声

将包含在读取的每个源文件末尾的重新构造的数据文本字符串。这是添加每个文件中都应该可用的替换的正确位置。例如：

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

    '''

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

版本0.6中的新功能

那么您的docstring就是：

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

    '''

令人惊叹的！我使用（例如，）

：ref:`

在一些表列标题中放置链接，这使得整个源表无法维护。将标题更改为仅

| topic |

会使编辑更加容易。