Sphinx公共API文档 [英] Sphinx Public API documentation

问题描述

我有大量的python文件，我想为我的项目生成公共API文档。所有这些功能都是我装饰的api的一部分。

例如：

  @api 
 def post_comment （评论）
帖子a 

 pass 
  

同一类中还有其他的公共方法，这些API分布在几个文件中，每个文件定义类的方法，一些方法有这个@api装饰器，我怎么能告诉Sphinx为公共API生成文档？

解决方案

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

http：// sphinx .pocoo.org / ext / autodoc.html＃event-autodoc-skip-member

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

这里是一个小例子在我的 conf.py 文件的末尾（这是t他为sphinx配置文件）

  def my_doc_skip（app，what，name，obj，skip，options）：
如果什么！=method：
 return True 
 
＃如果obj用@api 
＃返回True 
＃return False 
 
 def setup（app）：
 app.connect（'autodoc-process-docstring'，my_process_docstring）
 app.connect（'autodoc-skip-member'，my_doc_skip）
  

您还可以使用函数处理docstring。

I have a large number of python file and I would like to generate public API documentation for my project. All the functions that are part of the api I have decorated with a decorator.

for example:

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

There are other public methods in the same classes. The API is spread among several files each file defining classes with methods and some methods have this @api decorator. How can I tell Sphinx to generate docs just for the public API?

解决方案

I'm answering my own question... After some more had searching I found this:

http://sphinx.pocoo.org/ext/autodoc.html#event-autodoc-skip-member

Basically you can define a function in your conf.py file can look at each member and skip all that don't have the right decorator.

here is a little example at the end of my conf.py file (this is the config file for 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)

You can also process the docstring with a function.

这篇关于Sphinx公共API文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！