Merge pull request #20 from piyushk/piyushk/autodoc_disable_nested

Allow disabling nesting of autosummary tables

Author: Chilipp

.travis.yml

@@ -16,13 +16,16 @@ env:
   - SPHINX_VERSION=1.8.*
   - SPHINX_VERSION=2.0.*
   - SPHINX_VERSION=2.1.*
+  - SPHINX_VERSION=2.2.*
   - SPHINX_VERSION=""
 matrix:
   exclude:
     - python: "2.7"
       env: SPHINX_VERSION=2.0.*
     - python: "2.7"
       env: SPHINX_VERSION=2.1.*
+    - python: "2.7"
+      env: SPHINX_VERSION=2.2.*
     - python: "3.7"
       env: SPHINX_VERSION=1.3.*
     - python: "3.7"

autodocsumm/__init__.py

@@ -62,7 +62,7 @@
 #: Options of the :class:`sphinx.ext.autodoc.ModuleDocumenter` that have an
 #: effect on the selection of members for the documentation
 member_options = {
-    'members', 'undoc-members', 'inherited-members', 'exlude-members',
+    'members', 'undoc-members', 'inherited-members', 'exclude-members',
     'private-members', 'special-members', 'imported-members',
     'ignore-module-all'}
 
@@ -208,6 +208,7 @@ class AutoSummModuleDocumenter(ModuleDocumenter, AutosummaryDocumenter):
     #: but with additional autosummary boolean option
     option_spec = ModuleDocumenter.option_spec.copy()
     option_spec['autosummary'] = bool_option
+    option_spec['autosummary-no-nesting'] = bool_option
 
     #: Add options for members for the autosummary
     for _option in member_options.intersection(option_spec):
@@ -244,6 +245,7 @@ class AutoSummClassDocumenter(ClassDocumenter, AutosummaryDocumenter):
     #: but with additional autosummary boolean option
     option_spec = ClassDocumenter.option_spec.copy()
     option_spec['autosummary'] = bool_option
+    option_spec['autosummary-no-nesting'] = bool_option
 
     #: Add options for members for the autosummary
     for _option in member_options.intersection(option_spec):
@@ -399,10 +401,10 @@ class AutoSummDirective(AutodocDirective, Autosummary):
 
     if sphinx_version < [1, 7]:
         _default_flags = AutodocDirective._default_flags.union(
-            {'autosummary'} | set(map('autosummary-{}'.format, member_options))
+            {'autosummary', 'autosummary-no-nesting'} | set(map('autosummary-{}'.format, member_options))
             )
     else:
-        AUTODOC_DEFAULT_OPTIONS.append('autosummary')
+        AUTODOC_DEFAULT_OPTIONS.extend(['autosummary', 'autosummary-no-nesting'])
         AUTODOC_DEFAULT_OPTIONS.extend(
             map('autosummary-{}'.format, member_options))
 
@@ -463,7 +465,8 @@ def run(self):
             self.result = ViewList()
         documenter = self.autosummary_documenter
         grouped_documenters = documenter.get_grouped_documenters()
-        summ_nodes = self.autosumm_nodes(documenter, grouped_documenters)
+        nested = 'autosummary-no-nesting' not in self.options
+        summ_nodes = self.autosumm_nodes(documenter, grouped_documenters, nested)
 
         dn = summ_nodes.pop(documenter.fullname)
         if self.name == 'automodule':
@@ -559,7 +562,7 @@ def inject_summary(node):
             inject_summary(node)
         return doc_nodes
 
-    def autosumm_nodes(self, documenter, grouped_documenters):
+    def autosumm_nodes(self, documenter, grouped_documenters, nested):
         """Create the autosummary nodes based on the documenter content
 
         Parameters
@@ -570,6 +573,8 @@ def autosumm_nodes(self, documenter, grouped_documenters):
         grouped_documenters: dict
             The dictionary as it is returned from the
             :meth:`AutosummaryDocumenter.get_grouped_documenters` method
+        nested: bool
+            If true, autosummary tables will also be created for members.
 
         Returns
         -------
@@ -596,13 +601,14 @@ def autosumm_nodes(self, documenter, grouped_documenters):
                 ViewList(['**%s**' % section]), 0, node)
             this_nodes += node
             this_nodes += self.get_table(items)
-            for mdocumenter, check_module in documenters:
-                if (mdocumenter.objtype == 'class' and
-                        not (check_module and not mdocumenter.check_module())):
-                    if hasattr(mdocumenter, 'get_grouped_documenters'):
-                        summ_nodes.update(self.autosumm_nodes(
-                            mdocumenter, mdocumenter.get_grouped_documenters())
-                            )
+            if nested:
+                for mdocumenter, check_module in documenters:
+                    if (mdocumenter.objtype == 'class' and
+                            not (check_module and not mdocumenter.check_module())):
+                        if hasattr(mdocumenter, 'get_grouped_documenters'):
+                            summ_nodes.update(self.autosumm_nodes(
+                                mdocumenter, mdocumenter.get_grouped_documenters(), nested)
+                                )
         summ_nodes[documenter.fullname] = this_nodes
         return summ_nodes
 
@@ -781,12 +787,12 @@ def setup(app):
                 CallableAttributeDocumenter, NoDataDataDocumenter,
                 NoDataAttributeDocumenter]:
         if not issubclass(registry.get(cls.objtype), cls):
-            try:
-                # we use add_documenter because this does not add a new
-                # directive
-                app.add_documenter(cls)
-            except AttributeError:
+            if sphinx_version >= [2, 2]:
+                app.add_autodocumenter(cls, override=True)
+            elif sphinx_version >= [0, 6]:
                 app.add_autodocumenter(cls)
+            else:
+                app.add_documenter(cls)
 
     # directives
     if sphinx_version >= [1, 8]:

docs/conf_settings.rst

@@ -38,11 +38,16 @@ table: these are
 - ``autosummary-imported-members``
 - ``autosummary-ignore-module-all``
 - ``autosummary-members``
+- ``autosummary-no-nesting``
 
 They are essentially the same as the options for :mod:`~sphinx.ext.autodoc`
 (i.e. ``private-members`` or ``members``), but they only affect the
 autosummary table (see the example in :ref:`summary-table-example`).
 
+The new additional flag ``autosummary-no-nesting`` only generates
+autosummary tables for a module, but not for members within. See
+:ref:`no-nesting-example`.
+
 
 .. _confvals:
 

docs/examples.rst

@@ -114,3 +114,27 @@ which gives us
     :no-members:
     :autosummary:
     :autosummary-members:
+
+.. _no-nesting-example:
+
+Generating a summary table for the module without nesting
+---------------------------------------------------------
+
+Using the ``autosummary-no-nesting`` option, you can generate the autosummary
+table for a module without generating autosummary tables for members within
+that module. This is useful when you only want to use the autosummary table as
+a table of contents for a given page. For the :doc:`demo module <demo_module>`,
+here's an example::
+
+    .. automodule:: dummy
+        :autosummary:
+        :members:
+        :autosummary-no-nesting:
+
+which gives us
+
+.. automodule:: dummy
+    :noindex:
+    :members:
+    :autosummary:
+    :autosummary-no-nesting:

tests/sphinx_supp/index.rst

@@ -9,3 +9,4 @@ Example documentation
     test_class_summary_only
     test_inherited
     test_module_title
+    test_module_no_nesting

tests/sphinx_supp/test_module_no_nesting.rst

@@ -0,0 +1,5 @@
+Docs of dummy test module without nesting
+=========================================
+
+.. automodule:: dummy
+   :autosummary-no-nesting:

tests/test_autodocsumm.py

@@ -50,6 +50,26 @@ def test_module(self, app, status, warning):
         self.assertNotIn('Should also be skipped', html)
         self.assertIn('Should also be included', html)
 
+    @with_app(buildername='html', srcdir=sphinx_supp,
+              copy_srcdir_to_tmpdir=True)
+    def test_module_no_nesting(self, app, status, warning):
+        app.build()
+        html = get_html(app, 'test_module_no_nesting.html')
+
+        self.assertIn('<span class="pre">TestClass</span>', html)
+        self.assertIn('<span class="pre">test_func</span>', html)
+
+        # test whether the data is shown correctly
+        self.assertIn('<span class="pre">large_data</span>', html)
+        self.assertIn('<span class="pre">small_data</span>', html)
+
+        # test that elements of TestClass are not autosummarized, since nesting is disabled.
+        self.assertNotIn('<span class="pre">test_method</span>', html)
+        self.assertNotIn('<span class="pre">test_attr</span>', html)
+
+        # test the members are still displayed
+        self.assertIn('<dt id="dummy.Class_CallTest">', html)
+
     @with_app(buildername='html', srcdir=sphinx_supp,
               copy_srcdir_to_tmpdir=True)
     def test_module_summary_only(self, app, status, warning):