15

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

这是一个例子：

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

    '''

问题是，在为RealLongExampleClassName类创建文档时，我为 full path name 生成了它module1.module2.module3.module4.module5.ReallyLongExampleClassaName。

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

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

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

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

:class:`module1.module2.ReallyLongClassName`

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


编辑 2012 年 4 月 5 日：

根据 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 的回答！

4

4 回答 4

21

根据 sphinx 文档（https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects），您可以在目标类之前使用一个点：

:class:`.ReallyLongExampleClassName`

或者

:class:`.module5.ReallyLongExampleClassName`

让 sphinx 搜索类：

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

于 2012-04-08T21:43:40.670 回答
3

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

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

于 2015-07-10T10:26:50.300 回答
2

另一种策略是使用 reST Substitutions。:class:这将让您通过稍后调用交叉引用来节省文本中的更多空间：

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

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

    '''

如果您在许多文件中引用同一个类，则可以使用rst_epilog设置将替换项放在 Sphinx conf.py 文件中。从狮身人面像文档：

rst_epilog

将包含在每个读取的源文件末尾的 reStructuredText 字符串。这是添加应该在每个文件中可用的替换的正确位置。一个例子：

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

0.6 版中的新功能。

那么你的文档字符串就是：

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

    '''
于 2016-02-03T02:28:33.897 回答
1

在黑暗中狂野刺伤。也许这有效：

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

这将是有效的 Python

import scipy.\
stats
于 2012-04-05T22:06:35.557 回答