python - Sphinx 公共(public) API 文档

Question

我有大量 python 文件，我想为我的项目生成公共(public) API 文档。所有属于 api 一部分的功能我都用装饰器装饰了。

例如:

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

同一个类中还有其他公共(public)方法。 API 分布在几个文件中，每个文件都用方法定义类，一些方法有这个 @api 装饰器。我如何告诉 Sphinx 只为公共(public) 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)

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