'autodoc_default_flags'如何在python Sphinx配置中工作？

Question

我试图生成使用狮身人面像1.4和我的蟒蛇类的文档sphinx-apidoc和sphinx.ext.autodoc扩展.

我有很多模块,我希望每个模块只显示类名,但不是类中的完整方法列表(在我的代码中都有文档字符串).

这是我的conf.py文件的片段:

sys.path.insert(0, '/blah/sphinx/src')

extensions = ['sphinx.ext.autodoc']
autodoc_member_order = 'bysource'
autodoc_default_flags = ['no-members']

这是一个玩具模块(my_module.py),我用它来弄清楚Sphinx是如何工作的:

"""
==============
Test my module
==============
"""

def module_function():
    """Here is a module function, let's see if it's in"""
     print 'module level'

class TestClass:
    """
    Test this class

    Here is some more class documentation.
    """
    def __init__(self):
        """Here is init"""
        self.test = True

    def getName(self, inputName):
        """Summary for getName

        more documentation for getName
        """    
        print "hello"
        return inputName

我只展示了这个类的代码,以防我需要在我缺少的doc字符串中做些什么.

我运行sphinx-apidoc来生成第一个文件:

sphinx-apidoc -f -M -e -o docs// blah/sphinx/src /

然后建立:

制作HTML

我可能不清楚autodoc_default_flags应该做什么.我认为当你运行带有这些标志的sphinx-apidoc时,那些标志就被应用于.rst文件中的指令了.但是,在我运行sphinx-apidoc之后,我得到了这个.rst文件:

my_module module
=====================

.. automodule:: my_module
    :members:
    :undoc-members:
    :show-inheritance:

我不希望:members:因为设置这些标志而被应用,但它确实存在!并且html页面完全包含了他们的文档字符串.

FWIW autodoc_member_order正在工作; 我可以设置它来切换方法出现的顺序.

所以我的问题:

1. 是autodoc_default_flags应该做的事情我描述或我误解呢？
2. 如果它可以用于自动隐藏构建中的成员,我是否正确使用它？如果是这样,任何关于为什么我仍然被:members:添加到.rst文件的想法？
3. 如果我误解它,那它究竟做了什么？如何自动隐藏构建文档字符串？

理想情况下,我想要像SciPy这样的东西,例如:

http://docs.scipy.org/doc/scipy/reference/cluster.hierarchy.html

为此,我正在玩拿破仑和sphinx.ext.autosummary扩展,但似乎apidoc应该能够隐藏类方法文档.

Answer 1

我认为当你运行带有这些标志的sphinx-apidoc时,那些标志就被应用于.rst文件中的指令了.

sphinx-build确实适用autodoc_default_flags于conf.py,除非在*.rst文件中覆盖了标志.

sphinx-apidoc不使用conf.py.

可以通过环境变量自定义sphinx-apidoc生成的*.rst文件中的标志SPHINX_APIDOC_OPTIONS.例:

$ export SPHINX_APIDOC_OPTIONS=no-members
$ sphinx-apidoc -o docs/ /blah/sphinx/src/

这将导致automodule指令看起来像这样:

.. automodule:: my_module
   :no-members:

如果您需要更多地控制生成的输出,您可以编写自己的apidoc.py模块版本.请参阅自定义`sphinx-apidoc`的模板.