6

将 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
4

1 回答 1

0

而不是: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
于 2013-10-16T09:58:47.890 回答