Merge pull request #6 from takluyver/class_members_toctree-option

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

Author: pv

README.txt

@@ -40,6 +40,12 @@ The following options can be set in conf.py:
   Whether to show all members of a class in the Methods and Attributes
   sections automatically.
 
+- numpydoc_class_members_toctree: bool
+
+  Whether to create a Sphinx table of contents for the lists of class
+  methods and attributes. If a table of contents is made, Sphinx expects
+  each entry to have a separate page.
+
 - numpydoc_edit_link: bool  (DEPRECATED -- edit your HTML template instead)
 
   Whether to insert an edit link after docstrings.

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)