链接到 python 文档字符串中的类方法

Posted 2023-03-29

【中文标题】链接到 python 文档字符串中的类方法

【英文标题】：Link to class method in python docstring

【发布时间】：2014-02-12 22:00:18

【问题描述】：

我想从同一类的另一个方法的文档字符串中添加指向我的类中的方法的链接。我希望该链接可以在 sphinx 中使用，并且优先在 Spyder 和其他 Python IDE 中使用。

我尝试了几个选项，发现只有一个有效，但它很麻烦。

假设mymodule.py中的结构如下

def class MyClass():
    def foo(self):
        print 'foo'
    def bar(self):
        """This method does the same as <link to foo>"""
        print 'foo'

我为<link to foo> 尝试了以下选项：

:func:`foo` :func:`self.foo` :func:`MyClass.foo` :func:`mymodule.MyClass.foo`

唯一能有效产生链接的是:func:`mymodule.MyClass.foo`，但链接显示为mymodule.MyClass.foo()，我想要一个显示为foo()或foo的链接。 以上选项都不会在 Spyder 中生成链接。

感谢您的帮助。

【问题讨论】：

什么意思 "add ... from inside" ???链接和超链接有什么区别？

我将hyperlink 替换为link 以避免混淆。

我还是不太明白你的问题。您的意思是要从 Sphinx 或 Spyder 或其他 Python IDE 执行对函数 bar 的文档字符串的询问，该函数将提供信息 “您搜索的函数或方法是 foo” ?

其次，mymodule.MyClass.foo() 和 foo() 之间有什么区别？你怎么称呼 "display" ？是字符串的显示吗？或者你想要一个返回的对象？在后一种情况下，mymodule.MyClass.foo() 和 foo() 末尾的 paens 太多了。

很抱歉造成混乱，总是很难简明地解释一个问题。我只想有一个可以单击的链接，它将带您到 foo() 的文档字符串（在 IDE 的文档窗口中，或在 Sphinx 的 html 构建中）。关于括号：它们是正确的： :func:mymodule.MyClass.foo 导致链接带有括号。我再次稍微改述了这个问题。

【参考方案1】：

适用于 Sphinx 的解决方案是在引用前加上 ~。

根据Cross-referencing Syntax 上的 Sphinx 文档，

如果你在内容前面加上~，链接文本只会是最后一个 目标的组成部分。例如，:py:meth:~Queue.Queue.get 将 请参阅 Queue.Queue.get 但仅将 get 显示为链接文本。

所以答案是：

class MyClass():
    def foo(self):
        print 'foo'
    def bar(self):
        """This method does the same as :func:`~mymodule.MyClass.foo`"""
        print 'foo'

这会产生一个看起来像这样的 html：This method does the same as foo()，而foo() 是一个链接。

但是，请注意，这可能不会在 Spyder 中显示为链接。

【讨论】：

(Spyder dev here) @saroele 我计划在未来改善这种情况。我完全同意拥有它真的很酷；）

您可以使用:any: role 进行操作 - 请参阅有关default_setting 的说明。

是否可以在不使用完整模块路径的情况下进行交叉引用？

@Jonathan : 在 autodoc.rst 我使用 currentmodule : .. currentmodule:: mymodule .. autosummary:: mymodule.MyClass 并且在文档字符串中，只使用短名称就可以了。跨度>

我发现不是:func:，而是:meth:。

【参考方案2】：

如果您想手动指定可以使用的链接文本：

:func:`my text <mymodule.MyClass.foo>`

欲了解更多信息，请查看Cross-referencing Python objects。

【讨论】：

这行得通，谢谢。通过查看链接，我发现在引用前面加上 ~ 更接近我的需要。我已将其放在单独的答案中。然而，它仍然无法在 Spyder 中工作......

【参考方案3】：

在我看来，您只需在表达式中添加__name__ 或__doc__ 即可获得所需的内容。 我仍然不确定是否正确理解了目标

class MyClass():
    def foo(self):
        """I am the docstring of foo"""
        print 'foo'
    def bar(self):
        """This method does the same as <link to foo>"""
        print 'foo'

print
print MyClass.foo
print MyClass.foo.__name__
print MyClass.foo.__doc__
print
print MyClass.__dict__['foo']
print MyClass.__dict__['foo'].__name__
print MyClass.__dict__['foo'].__doc__

结果

<unbound method MyClass.foo>
foo
I am the docstring of foo

<function foo at 0x011C27B0>
foo
I am the docstring of foo

【讨论】：

我认为您错过了问题的重点：我想在 Sphinx 构建的文档的 html 中添加一个链接（超链接）。

你说得对，我没抓住重点。那是因为我不认识斯芬克斯。所以我尝试安装狮身人面像。但我没有成功。我在 Windows 上，我尝试按照文档中的说明使用 sphinx-quickstart。但我认为我对安装过程有误解。我帮不了你，对不起。我不知道 Sphinx 上下文中的“超链接”必须了解什么。