sphinx方法返回带有链接的类型

Question

将cython与-Xembedsignature=True一起使用可能会在文档字符串中产生以下形式的签名：

|  mymethod(...)
|      MyCythonModule.mymethod(self, param1, MyCythonType param2, param3=None) -> SomeResultType

当使用autodoc扩展为此生成Sphinx文档时，输出如下：

mymethod(self, param1, MyCythonType param2, param3=None) → SomeResultType

问题是MyCythonType和SomeResultType都不是HTML文档中的超链接，这使得文档浏览起来有点不太理想。

Sphinx为文档开发人员提供了挂接"autodoc流程签名"事件的可能性，这使得能够实时操作签名。该方法应返回一个(signature, return_annotation)元组。当修改return_anotation结果以插入诸如"SomeResultType"或：class:SomeResultType等内容时，它只是没有格式化，而是按原样出现在HTML文档中，没有链接，并且在字符串中附加/准备了任何内容。

我可以看到，类型化参数可能必须被忽略，因为Python没有类似的东西，但必须可以为返回类型获取到其类文档的超链接，但我没有主意。

在编写了一个小的测试用例后，这似乎也会影响Python，而不仅仅是Cython:

class Foo(object):
def __init__(self):
pass
def get_bar(self):
"""
get_bar(self) -> Bar     <- here you see 'Bar', it will not
become a hyperlink, not even if
enclosed in ``
Get `Bar` from foo       <- here you see Bar again, it will
become a hyperlink
:returns: the bar
"""
return Bar()
class Bar(object):
def __init__(self):
pass

Answer 1

您应该尝试:class:`Bar`而不是:returns: the bar。

所以，像这样：

class Foo(object):
def __init__(self):
pass
def get_bar(self):
'''Get :class:`Bar` from :class:`Foo`
:returns: the :class:`Bar`
'''
return Bar()

class Bar(object):
def __init__(self):
pass