Question

我正在研究我的Python模块的文档（使用Sphinx和reST），我发现当交叉引用其他Python对象（模块，类，函数等）时，完整的对象名称最终会令人难以置信长。通常它超过80个字符，我想不惜一切代价避免。

以下是一个例子：

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

    '''

问题是，在为 ReallyLongExampleClassName 类创建文档时，我为完整路径名模块生成了它。模块1.module2.module3.module4.module5.ReallyLongExampleClassaName。

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

1）在模块名称的中间添加换行符。例如：

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

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

:class:`module1.module2.ReallyLongClassName`

我认为，由于ReallyLongClassName的文档与完整路径名相关联，Sphinx无法将缩短版本与完全命名的版本相关联。

非常感谢任何帮助。

编辑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

根据sphinx文档（http://sphinx.pocoo.org/domains.html?highlight=current#cross-referencing-python-objects），您可以在目标类之前使用一个点：

:class:`.ReallyLongExampleClassName`

或

:class:`.module5.ReallyLongExampleClassName`

让sphinx搜索课程：

...如果名称以点为前缀，并且未找到完全匹配，则将目标作为后缀，并搜索具有该后缀的所有对象名称。例如，：py：meth：.TarFile.close引用tarfile.TarFile.close（）函数，即使当前模块不是tarfile。由于这可能会模棱两可，如果有多个可能的匹配，您将收到Sphinx的警告。

Answer 2

您可以使用~作为前缀，它完全符合您的要求。

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

Answer 3

另一种策略是使用reST Substitutions。通过稍后调用:class:交叉引用，您可以在文本中节省更多空间：

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

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

    '''

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

<强> rst_epilog

一串reStructuredText，它将包含在每个读取的源文件的末尾。这是添加应在每个文件中可用的替换的正确位置。一个例子：
rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""
版本0.6中的新功能。

然后你的docstring就是：

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引用长名称

4 个答案: