GH-43: Add support for autosummary-nosignatures option.

Author: dgilland

autodocsumm/__init__.py

@@ -250,6 +250,8 @@ def add_autosummary(self):
                 self.add_line('', sourcename)
 
                 self.add_line('.. autosummary::', sourcename)
+                if self.options.autosummary_nosignatures:
+                    self.add_line('    :nosignatures:', sourcename)
                 self.add_line('', sourcename)
                 indent = '    '
 
@@ -280,6 +282,7 @@ class AutoSummModuleDocumenter(ModuleDocumenter, AutosummaryDocumenter):
     option_spec['autosummary-sections'] = list_option
     option_spec['autosummary-no-titles'] = bool_option
     option_spec['autosummary-force-inline'] = bool_option
+    option_spec['autosummary-nosignatures'] = bool_option
 
     #: Add options for members for the autosummary
     for _option in member_options.intersection(option_spec):
@@ -329,6 +332,7 @@ class AutoSummClassDocumenter(ClassDocumenter, AutosummaryDocumenter):
     option_spec['autosummary-sections'] = list_option
     option_spec['autosummary-no-titles'] = bool_option
     option_spec['autosummary-force-inline'] = bool_option
+    option_spec['autosummary-nosignatures'] = bool_option
 
     #: Add options for members for the autosummary
     for _option in member_options.intersection(option_spec):

docs/conf_settings.rst

@@ -56,6 +56,8 @@ autosummary table (see the example in :ref:`summary-table-example`).
 ``autosummary-force-inline``
     Force adding the autosummary, even it is already contained in the class
     or module docstring. See the example about :ref:`autosummary-position-example`
+``autosummary-nosignatures``
+    Do not show function signatures in the summary table.
 
 
 .. _directives:

docs/examples.rst

@@ -140,6 +140,29 @@ which gives us
     :autosummary-no-nesting:
 
 
+.. _nosignatures-example:
+
+Generating a summary table without signatures
+---------------------------------------------
+
+Using the ``autosummary-nosignatures`` option, you can generate the
+autosummary table for a module that will not include function signatures.
+This is useful for giving a high-level overview of the function name and
+description. For the :doc:`demo module <demo_module>`, here's an example::
+
+    .. automodule:: dummy
+        :members:
+        :autosummary:
+        :autosummary-nosignatures:
+
+which gives us
+
+.. automodule:: dummy
+    :members:
+    :autosummary:
+    :autosummary-nosignatures:
+
+
 .. _select-sections-example:
 
 Select the sections to document

tests/sphinx_supp/test_autoclasssumm_nosignatures.rst

@@ -0,0 +1,7 @@
+Autoclasssumm of Dummy Class without signatures
+===============================================
+
+.. autoclasssumm:: dummy.TestClass
+    :no-members:
+    :autosummary-members:
+    :autosummary-nosignatures:

tests/sphinx_supp/test_automodulesumm_nosignatures.rst

@@ -0,0 +1,7 @@
+Automodulesumm of dummy test module without signatures
+======================================================
+
+.. automodulesumm:: dummy
+    :no-members:
+    :autosummary-members:
+    :autosummary-nosignatures:

tests/sphinx_supp/test_class_nosignatures.rst

@@ -0,0 +1,7 @@
+Dummy Class Doc without signatures
+==================================
+
+.. autoclass:: dummy.TestClass
+    :no-members:
+    :autosummary-members:
+    :autosummary-nosignatures:

tests/sphinx_supp/test_module_nosignatures.rst

@@ -0,0 +1,7 @@
+Docs of dummy test module without signatures
+============================================
+
+.. automodule:: dummy
+    :no-members:
+    :autosummary-members:
+    :autosummary-nosignatures:

tests/test_autodocsumm.py

@@ -185,6 +185,22 @@ def test_module_with_title(self, app, status, warning):
         else:
             self.assertNotIn('Should also be skipped', html)
 
+    @with_app(buildername='html', srcdir=sphinx_supp,
+        copy_srcdir_to_tmpdir=True)
+    def test_module_nosignatures(self, app, status, warning):
+        app.build()
+
+        html = get_html(app, 'test_module_nosignatures.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)
+
+        self.assertNotIn('<dt id="dummy.Class_CallTest">', html)
+        self.assertNotIn('()', html)
+
     @with_app(buildername='html', srcdir=sphinx_supp,
               copy_srcdir_to_tmpdir=True)
     def test_class(self, app, status, warning):
@@ -291,6 +307,34 @@ def test_class_summary_only(self, app, status, warning):
 
         self.assertNotIn('<dt id="dummy.TestClass.small_data">', html)
 
+    @with_app(buildername='html', srcdir=sphinx_supp,
+        copy_srcdir_to_tmpdir=True)
+    def test_class_nosignatures(self, app, status, warning):
+        app.build()
+        html = get_html(app, '/test_class_nosignatures.html')
+
+        if sphinx_version[:2] > [3, 1]:
+            self.assertIn(
+                '<span class="pre">instance_attribute</span>',
+                html)
+        elif sphinx_version[:2] < [3, 1]:
+            self.assertIn(
+                '<span class="pre">dummy.TestClass.instance_attribute</span>',
+                html)
+
+        self.assertIn('<span class="pre">test_method</span>', html)
+        self.assertIn('<span class="pre">test_attr</span>', html)
+
+        # test whether the right objects are included
+        self.assertIn('<span class="pre">class_caller</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)
+
+        self.assertNotIn('<dt id="dummy.TestClass.small_data">', html)
+        self.assertNotIn('()', html)
+
     @with_app(buildername='html', srcdir=sphinx_supp,
               copy_srcdir_to_tmpdir=True)
     def test_inherited(self, app, status, warning):
@@ -381,6 +425,23 @@ def test_autoclasssumm_some_sections(self, app, status, warning):
         self.assertIn('<span class="pre">class_caller</span>', html)
         self.assertIn('<span class="pre">test_attr</span>', html)
 
+    @with_app(buildername='html', srcdir=sphinx_supp,
+        copy_srcdir_to_tmpdir=True)
+    def test_autoclasssumm_nosignatures(self, app, status, warning):
+        """Test building the autosummary of a class without signatures."""
+        app.build()
+
+        html = get_html(app, '/test_autoclasssumm_nosignatures.html')
+
+        # the class docstring must not be in the html
+        self.assertNotIn("Class test for autosummary", html)
+
+        # test if the methods and attributes are there in a table
+        self.assertIn('<span class="pre">test_method</span>', html)
+        self.assertIn('<span class="pre">test_attr</span>', html)
+
+        self.assertNotIn('()', html)
+
     @with_app(buildername='html', srcdir=sphinx_supp,
               copy_srcdir_to_tmpdir=True)
     def test_automodulesumm(self, app, status, warning):
@@ -413,6 +474,24 @@ def test_automodulesumm_some_sections(self, app, status, warning):
         self.assertIn('<span class="pre">large_data</span>', html)
         self.assertIn('<span class="pre">test_func</span>', html)
 
+    @with_app(buildername='html', srcdir=sphinx_supp,
+        copy_srcdir_to_tmpdir=True)
+    def test_automodulesumm_nosignatures(self, app, status, warning):
+        """Test building the autosummary of a module without signatures."""
+        app.build()
+
+        html = get_html(app, '/test_automodulesumm_nosignatures.html')
+
+        # the class docstring must not be in the html
+        self.assertNotIn("Module for testing the autodocsumm", html)
+
+        # test if the classes, data and functions are there in a table
+        self.assertIn('<span class="pre">Class_CallTest</span>', html)
+        self.assertIn('<span class="pre">large_data</span>', html)
+        self.assertIn('<span class="pre">test_func</span>', html)
+
+        self.assertNotIn('()', html)
+
     @with_app(buildername='html', srcdir=sphinx_supp,
               copy_srcdir_to_tmpdir=True)
     def test_empty(self, app, status, warning):