python - Sphinx 公共 API 文档

Question

我有大量的 python 文件，我想为我的项目生成公共 API 文档。我用装饰器装饰的 api 的所有功能。

例如：

@api
def post_comment(comment)"
    """ Posts a coment
    """
    pass

同一类中还有其他公共方法。API 分布在几个文件中，每个文件定义了带有方法的类，并且一些方法有这个 @api 装饰器。如何告诉 Sphinx 仅为公共 API 生成文档？

Answer 1

我正在回答我自己的问题......经过更多搜索后，我发现了这个：

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#skipping-members

基本上，您可以在conf.py文件中定义一个函数，可以查看每个成员并跳过所有没有正确装饰器的函数。

这是我文件末尾的一个小示例conf.py（这是 sphinx 的配置文件）：

def my_doc_skip(app, what, name, obj, skip, options):
    if what != "method":
        return True

    # if obj is decorated with @api
    #     return True
    # return False

def setup(app):
    app.connect('autodoc-process-docstring', my_process_docstring)
    app.connect('autodoc-skip-member', my_doc_skip)

您还可以使用函数处理文档字符串。