diff --git a/sphinx_automodapi/automodapi.py b/sphinx_automodapi/automodapi.py index 411e7b1..e82eb37 100644 --- a/sphinx_automodapi/automodapi.py +++ b/sphinx_automodapi/automodapi.py @@ -54,8 +54,14 @@ 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 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 +247,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 +267,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: @@ -327,6 +337,10 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None, clsfuncoptions.append(':inherited-members:') if inherited_members is False: clsfuncoptions.append(':no-inherited-members:') + if ignore_emptydoc is True: + clsfuncoptions.append(':ignore-emptydoc:') + if ignore_emptydoc is False: + clsfuncoptions.append(':no-ignore-emptydoc:') clsfuncoptionstr = '\n '.join(clsfuncoptions) if hasfuncs: diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 61525eb..4136cc9 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -46,7 +46,13 @@ 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 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 +62,18 @@ 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 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 +136,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 +283,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 +423,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 +573,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 == 'method' + 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 +689,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}