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

Question

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

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

这是我的 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

我只显示此 class 的代码，以防我需要在缺少的文档字符串中执行某些操作。

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

sphinx-apidoc -f -M -e -o 文档//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 正在工作；我可以设置它来切换方法出现的顺序。

所以我的问题：

autodoc_default_flags 是否应该按照我描述的那样做，还是我误解了？
如果它可以用于从构建中自动隐藏成员，我是否正确使用了它？如果是这样，关于为什么我仍然将 :members: 添加到 .rst 文件有什么想法吗？
如果我误解了它，那么它到底有什么作用？以及如何从我的构建中自动隐藏方法文档字符串？

理想情况下我想要像 SciPy 这样的东西，例如这里：

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

为此，我正在研究 Napoleon 和 sphinx.ext.autosummary 扩展，但似乎 apidoc 本身应该能够隐藏 class 方法文档。

Answer 1

I thought that when you ran sphinx-apidoc with those flags set, then those flags were applied to the directives in the .rst files.

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 模块版本。参见。

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

How does 'autodoc_default_flags' work in python Sphinx configuration?

python

python-sphinx

autodoc

numpydoc

sphinx-napoleon