Add ignore_emptydoc global option and flags

lukelbd · lukelbd · commit 12b65a5be26d · 2020-05-24T18:45:55.000-06:00
diff --git a/sphinx_automodapi/automodapi.py b/sphinx_automodapi/automodapi.py
@@ -54,8 +54,15 @@
         The global sphinx configuration option
         ``automodsumm_inherited_members`` decides if members that a class
         inherits from a base class are included in the generated
-        documentation. The option ``:inherited-members:`` or ``:no-inherited-members:``
-        allows the user to overrride the global setting.
+        documentation. The flags ``:inherited-members:`` or ``:no-inherited-members:``
+        allow the user to overrride the global setting.
+
+    * ``:ignore-emptydoc:`` or ``:no-ignore-emptydoc:``
+        The global sphinx configuration option ``automodsumm_ignore_emptydoc``
+        decides if functions, classes, and class methods with empty
+        ``__doc__`` attributes are included in the generated documentation. The flags
+        ``:ignore-emptydoc:`` or ``:no-ignore-emptydoc:`` allow the user to override
+        the global setting.
 
 
 This extension also adds four sphinx configuration options:
@@ -241,7 +248,7 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None,
 
             # look for actual options
             unknownops = []
-            inherited_members = None
+            inherited_members = ignore_emptydoc = None
             for opname, args in _automodapiargsrex.findall(spl[grp * 3 + 2]):
                 if opname == 'skip':
                     toskip.append(args.strip())
@@ -261,6 +268,10 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None,
                     inherited_members = True
                 elif opname == 'no-inherited-members':
                     inherited_members = False
+                elif opname == 'ignore-emptydoc':
+                    ignore_emptydoc = True
+                elif opname == 'no-ignore-emptydoc':
+                    ignore_emptydoc = False
                 elif opname == 'include-all-objects':
                     allowothers = True
                 else:
@@ -322,6 +333,10 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None,
                 clsfuncoptions.append(':skip: ' + ','.join(toskip))
             if allowedpkgnms:
                 clsfuncoptions.append(allowedpkgnms)
+            if ignore_emptydoc is True:
+                clsfuncoptions.append(':ignore-emptydoc:')
+            if ignore_emptydoc is False:
+                clsfuncoptions.append(':no-ignore-emptydoc:')
             if hascls:  # This makes no sense unless there are classes.
                 if inherited_members is True:
                     clsfuncoptions.append(':inherited-members:')
diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py
@@ -46,7 +46,14 @@
         in the generated documentation. The flags ``:inherited-members:`` or
         ``:no-inherited-members:`` allows overrriding this global setting.
 
-This extension also adds two sphinx configuration options:
+    * ``:ignore-emptydoc:`` or ``:no-ignore-emptydoc:``
+        The global sphinx configuration option ``automodsumm_ignore_emptydoc``
+        decides if functions, classes, and class methods with empty
+        ``__doc__`` attributes are included in the generated documentation. The flags
+        ``:ignore-emptydoc:`` or ``:no-ignore-emptydoc:`` allows overrriding this
+        global setting.
+
+This extension also adds three sphinx configuration options:
 
 * ``automodsumm_writereprocessed``
     Should be a bool, and if ``True``, will cause `automodsumm`_ to write files
@@ -56,12 +63,19 @@
     cause of sphinx warnings or other debugging.  Defaults to ``False``.
 
 * ``automodsumm_inherited_members``
-    Should be a bool and if ``True``, will cause `automodsumm`_ to document
+    Should be a bool, and if ``True``, will cause `automodsumm`_ to document
     class members that are inherited from a base class. This value can be
     overriden for any particular automodsumm directive by including the
     ``:inherited-members:`` or ``:no-inherited-members:`` options.  Defaults to
     ``False``.
 
+* ``automodsumm_ignore_emptydoc``
+    Should be a bool, and if ``True``, will cause `automodsumm`_ to ignore
+    functions, classes, and class methods with empty ``__doc__`` attributes.
+    This value can be overridden for any particular automodsumm directive by including
+    the ``:ignore-emptydoc:`` or ``:no-ignore-emptydoc:`` options. Defaults to
+    ``False``.
+
 .. _sphinx.ext.autosummary: http://sphinx-doc.org/latest/ext/autosummary.html
 .. _autosummary: http://sphinx-doc.org/latest/ext/autosummary.html#directive-autosummary
 
@@ -124,6 +138,8 @@ class Automodsumm(Autosummary):
     option_spec['allowed-package-names'] = _str_list_converter
     option_spec['inherited-members'] = flag
     option_spec['no-inherited-members'] = flag
+    option_spec['ignore-emptydoc'] = flag
+    option_spec['no-ignore-emptydoc'] = flag
 
     def run(self):
         env = self.state.document.settings.env
@@ -269,6 +285,7 @@ def process_automodsumm_generation(app):
             generate_automodsumm_docs(
                 lines, sfn, app=app, builder=app.builder,
                 suffix=suffix, base_path=app.srcdir,
+                ignore_emptydoc=app.config.automodsumm_ignore_emptydoc,
                 inherited_members=app.config.automodsumm_inherited_members)
 
 
@@ -408,6 +425,7 @@ def automodsumm_to_autosummary_lines(fn, app):
 def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst',
                               base_path=None, builder=None,
                               template_dir=None,
+                              ignore_emptydoc=False,
                               inherited_members=False):
     """
     This function is adapted from
@@ -557,6 +575,12 @@ def get_members_class(obj, typ, include_public=[],
                         documenter = get_documenter(app, safe_getattr(obj, name), obj)
                     except AttributeError:
                         continue
+                    if (
+                        ignore_emptydoc
+                        and documenter.objtype in ('method', 'class', 'function')
+                        and not getattr(safe_getattr(obj, name), '__doc__', '')
+                    ):
+                        continue
                     if typ is None or documenter.objtype == typ:
                         items.append(name)
                     elif typ == 'attribute' and documenter.objtype == 'property':
@@ -667,6 +691,7 @@ def setup(app):
 
     app.add_config_value('automodsumm_writereprocessed', False, True)
     app.add_config_value('automodsumm_inherited_members', False, 'env')
+    app.add_config_value('automodsumm_ignore_emptydoc', False, 'env')
 
     return {'parallel_read_safe': True,
             'parallel_write_safe': True}
