使用 Python Sphinx 引用长名称 [英] Referencing long names with Python Sphinx

问题描述

我正在为我的 Python 模块编写文档(使用 Sphinx 和 reST)，我发现当交叉引用其他 Python 对象(模块、类、函数等)时，完整的对象名称最终令人难以置信长.通常它超过 80 个字符，我想不惜一切代价避免这种情况.

I'm working on documentation for my Python module (using Sphinx and reST), and I'm finding that when cross-referencing other Python objects (modules, classes, functions, etc) the full object name ends up being incredibly long. Often it is longer than 80 characters, which I would like to avoid at all costs.

这是一个例子:

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

    '''

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

The issue is that when creating the documentation for the ReallyLongExampleClassName class, I generated it for the full path name module1.module2.module3.module4.module5.ReallyLongExampleClassaName.

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

I'm wondering if there is any way to solve this? I have tried the following methods, with no success:

1) 在模块名称中间添加换行符.示例:

1) Adding a line break in the middle of the module name. Example:

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

2) 以不同的(但仍然是 Python 可导入的)方式引用类名.示例:

2) Referencing the class name in a different (but still Python importable) way. Example:

:class:`module1.module2.ReallyLongClassName`

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

I believe that since the documentation for ReallyLongClassName is tied to the full path names that Sphinx cannot correlate the shortened version with the fully named version.

编辑 04/05/2012:

根据 j13r 的回答/建议(见下文)，我尝试了以下操作:

As per the answer/suggestion of j13r (see below) I tried the following:

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

这成功了.让它工作的唯一警告是第二行之前不能有空格(这在文档字符串中使用时非常令人沮丧).因此，为了使我的原始示例工作，它看起来像:

And this worked successfully. The only caveat to get this to work, is that the second line must not have spaces before it (which is quite frustrating when using this in a docstring). Thus to make my original example work it would look like:

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

    '''

很好，也很丑.如果您在 ReallyLongExampleClassName 之前放置空格以将其缩进与其上方的行相同的级别，则输出将包含空格，因此 Sphinx 将尝试引用类似 module1.module2.module3 的内容.module4.module5.ReallyLongExampleClassName.

Nice, and ugly. If you were to put spaces before ReallyLongExampleClassName to indent it to the same level as the line above it the output would include the spaces and thus Sphinx would try to reference something like module1.module2.module3.module4.module5.ReallyLongExampleClassName.

我还应该注意，我尝试了其他两种变体，但没有奏效:

I should also note that I tried two other variations of this, which did NOT work:

    # 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 个字符的行.

I was looking for a solution that didn't involve destroying the formatting of the docstring, but I suppose it will do...I think I actually prefer a line that goes past 80 characters to this.

感谢 j13r 的回答！

Thanks to j13r for the answer!

推荐答案

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

According to the sphinx documentation (https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects) you could use a dot before your target class:

:class:`.ReallyLongExampleClassName`

或

:class:`.module5.ReallyLongExampleClassName`

然后让 sphinx 搜索类:

and let sphinx search for the class:

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

... if the name is prefixed with a dot, and no exact match is found, the target is taken as a suffix and all object names with that suffix are searched. For example, :py:meth:.TarFile.close references the tarfile.TarFile.close() function, even if the current module is not tarfile. Since this can get ambiguous, if there is more than one possible match, you will get a warning from Sphinx.

这篇关于使用 Python Sphinx 引用长名称的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！