sunpy/sunpy — pull request #491 by derdon (2013-07-07 14:13:56+00:00)
Title: [documentation] exclude inherited methods reduce the number of warning from more than 600 to 26 by changing one line

While documenting the database package, it annoyed me that the rst directive ``.. autoclass:: sunpy.database.caching.BaseCache`` also lists all the inherited methods from OrderedDict like ``items()``, ``itervalues()`` etc. Setting the option ``numpydoc_show_class_members = False`` in conf.py solves this issue. Note that this also affects already existing classes like sunpy.map.MapMeta. It also reduces the number of docutils warnings from 673 to 26. What confused me though are the previous lines before the one I uncommented::

# Uncomment this to stop numpydoc from autolisting class members, which
# generates a ridiculous number of warnings.

Uncommenting didn't generate a high number of warnings but reduced it. The disadvantage of this change is that methods have to be always explicitly documented. Compare the documentation of sunpy.map.MapCube with and without the option ``numpydoc_show_class_members`` enabled.

This PR is not a perfect solution to this problem and is of course open for discussion.

Some background info: If the Sphinx extension autodoc was used directly instead of the numpy extension, inherited members would have been included in the API documentation explicitly by using the ``:inherited-members:`` option.