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

Question

我正在尝试使用Sphinx 1.4和sphinx-apidoc以及sphinx.ext.autodoc扩展为我的python类生成文档。

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

这是我的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确实在conf.py中应用autodoc_default_flags，除非在* .rst文件中覆盖了标志。

sphinx-apidoc不使用conf.py.

---

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

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

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

.. automodule:: my_module
   :no-members:

如果您需要更多地控制生成的输出，您可以编写自己的apidoc.py模块版本。见Customize templates for `sphinx-apidoc`。