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-process-signature'事件的可能性,该事件可以动态操作签名.该方法应该返回一个(signature, return_annotation)元组.当修改return_annotation结果以插入诸如`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

相反，:returns: the bar你应该尝试:class:`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