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:
autodoc_default_flags
supposed to do what I described or am I misunderstanding it?:members:
added to the .rst files?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.
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`.