Add config option for adding :toctree: on autosummary lists.

IPython uses some lists of class attributes and methods, but we don't
generate separate doc pages for each entry, so Sphinx throws warnings
about "toctree contains reference to nonexisting document".

This adds a Sphinx option called 'numpydoc_class_members_toctree',
defaulting to True, controlling whether the autosummary lists are
generated with the :toctree: option. Setting it to False suppresses
these warnings, but prevents the lists acting as tables of contents.

Addresses issue gh-5.

Author: takluyver

numpydoc/docscrape_sphinx.py

@@ -13,9 +13,13 @@
 
 class SphinxDocString(NumpyDocString):
     def __init__(self, docstring, config={}):
-        self.use_plots = config.get('use_plots', False)
+        # Subclasses seemingly do not call this.
         NumpyDocString.__init__(self, docstring, config=config)
 
+    def load_config(self, config):
+        self.use_plots = config.get('use_plots', False)
+        self.class_members_toctree = config.get('class_members_toctree', True)
+
     # string conversion routines
     def _str_header(self, name, symbol='`'):
         return ['.. rubric:: ' + name, '']
@@ -117,8 +121,10 @@ def _str_member_list(self, name):
                     others.append((param, param_type, desc))
 
             if autosum:
-                out += ['.. autosummary::', '   :toctree:', '']
-                out += autosum
+                out += ['.. autosummary::']
+                if self.class_members_toctree:
+                    out += ['   :toctree:']
+                out += [''] + autosum
 
             if others:
                 maxlen_0 = max(3, max([len(x[0]) for x in others]))
@@ -233,17 +239,18 @@ def __str__(self, indent=0, func_role="obj"):
 
 class SphinxFunctionDoc(SphinxDocString, FunctionDoc):
     def __init__(self, obj, doc=None, config={}):
-        self.use_plots = config.get('use_plots', False)
+        self.load_config(config)
         FunctionDoc.__init__(self, obj, doc=doc, config=config)
 
 class SphinxClassDoc(SphinxDocString, ClassDoc):
     def __init__(self, obj, doc=None, func_doc=None, config={}):
-        self.use_plots = config.get('use_plots', False)
+        self.load_config(config)
         ClassDoc.__init__(self, obj, doc=doc, func_doc=None, config=config)
 
 class SphinxObjDoc(SphinxDocString):
     def __init__(self, obj, doc=None, config={}):
         self._f = obj
+        self.load_config(config)
         SphinxDocString.__init__(self, doc, config=config)
 
 def get_doc_object(obj, what=None, doc=None, config={}):

numpydoc/numpydoc.py

@@ -38,7 +38,9 @@ def mangle_docstrings(app, what, name, obj, options, lines,
                       reference_offset=[0]):
 
     cfg = dict(use_plots=app.config.numpydoc_use_plots,
-               show_class_members=app.config.numpydoc_show_class_members)
+               show_class_members=app.config.numpydoc_show_class_members,
+               class_members_toctree=app.config.numpydoc_class_members_toctree,
+              )
 
     if what == 'module':
         # Strip top title
@@ -114,6 +116,7 @@ def setup(app, get_doc_object_=get_doc_object):
     app.add_config_value('numpydoc_edit_link', None, False)
     app.add_config_value('numpydoc_use_plots', None, False)
     app.add_config_value('numpydoc_show_class_members', True, True)
+    app.add_config_value('numpydoc_class_members_toctree', True, True)
 
     # Extra mangling domains
     app.add_domain(NumpyPythonDomain)