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

sphinx方法返回带链接的类型

1 个答案: