How does 'autodoc_default_flags' work in python Sphinx configuration?

Question

I am trying to generate documentation for my python classes using Sphinx 1.4 and sphinx-apidoc and the sphinx.ext.autodoc extension.

I have a lot of modules and I want each to only show class names, but not the full list of methods in the class (which all have docstrings in my code).

Here is a snippet of my conf.py file:

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

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

Here is a toy module (my_module.py) that I'm using to figure out how Sphinx works:

"""
==============
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

I'm only showing the code for this class in case there's something I need to be doing in the doc-strings that I'm missing.

I run sphinx-apidoc to generate the rst files:

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

then build:

make html

I might not be clear about what autodoc_default_flags should be doing. I thought that when you ran sphinx-apidoc with those flags set, then those flags were applied to the directives in the .rst files. However, after I run sphinx-apidoc, I get this .rst file:

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

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

I wouldn't have expected :members: to be applied due to setting those flags, but there it is! And the html page has the methods fully there along with their docstrings.

FWIW, autodoc_member_order is working; I can set it to switch the order the methods appear.

So my questions:

1. Is autodoc_default_flags supposed to do what I described or am I misunderstanding it?
2. If it can be used to automatically hide members from the build, am I using it correctly? If so, any thoughts about why I'm still getting :members: added to the .rst files?
3. If I'm misunderstanding it, then what does it really do? And how can I hide the method docstring from my build automatically?

Ideally I want something like SciPy has, for example here:

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

For that I'm playing around with Napoleon and the sphinx.ext.autosummary extensions, but it seems like apidoc alone should be able to hide class method documentation.

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 does apply autodoc_default_flags in conf.py, unless the flags are overridden in *.rst files.

sphinx-apidoc does not use conf.py.

---

It is possible to customize the flags in the *.rst files generated by sphinx-apidoc via the SPHINX_APIDOC_OPTIONS environment variable. Example:

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

This will result in automodule directives that look like this:

.. automodule:: my_module
   :no-members:

If you need more control over the generated output, you could perhaps write your own version of the apidoc.py module. See Customize templates for `sphinx-apidoc`.