使用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的文档与完整路径名绑定，因此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

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

Answer 2

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

Answer 3

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

Answer 4

在黑暗中狂刺。也许这可行：