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 文档中，没有链接，并且带有附加/附加到字符串的任何内容。

我可以看到 typed 参数可能必须被忽略，因为 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