Python狮身人面像引用长名称 [英] Python Sphinx referencing long names

问题描述

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

以下是一个示例：

  def exampleFunction（）：
'''这是一个引用另一个
的示例docstr：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` 
  

这个工作成功了。唯一需要注意的是，第二行不能在它之前有空格（这在docstring中使用时非常令人沮丧）。因此，使我的原始示例工作，它将如下所示：

  def exampleFunction（）：
'''一个示例docstring引用另一个
：class：`module1.module2.module3.module4.module5.\ 
 ReallyLongExampleClassName` 
 
'''
  

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

我还应该注意到，我尝试了另外两个这样的变体，这不起作用：

 ＃注意：尝试在'\'
：class：`module1.module2.module3.module4.module5之前放置一个空格。 \ 
 ReallyLongExampleClassName` 
 
＃注意：尝试省略'\'
：class：`module1.module2.module3.module4.module5。 
 ReallyLongExampleClassName` 
  

我正在寻找一种不涉及破坏格式化的解决方案docstring，但是我想它会做...我想我实际上更喜欢一个超过80个字符的行。

感谢j13r的答案！ / p>

解决方案

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

 ：class：`.ReallyLongExampleClassName` 
  

或

 ：class：`.module5.ReallyLongExampleClassName` 
  

并让sphinx搜索课程：

...如果名称前缀有一个点，并且没有找到完全匹配的话，那么这个targe将t作为后缀，并搜索具有该后缀的所有对象名称。例如：py：meth： .TarFile.close 引用tarfile.TarFile.close（）函数，即使当前模块不是tarfile。因为这可能会变得模棱两可，如果有多个可能的匹配，您将收到Sphinx的警告。

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.

Here is an example:

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

    '''

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) Adding a line break in the middle of the module name. Example:

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

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

:class:`module1.module2.ReallyLongClassName`

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.

Any help will be greatly appreciated.

Edit 04/05/2012:

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`

    '''

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`

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.

Thanks to j13r for the answer!

解决方案

According to the sphinx documentation (http://sphinx.pocoo.org/domains.html?highlight=current#cross-referencing-python-objects) you could use a dot before your target class:

:class:`.ReallyLongExampleClassName`

or

:class:`.module5.ReallyLongExampleClassName`

and let sphinx search for the class:

... 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狮身人面像引用长名称的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！