From 12b65a5be26de1b53b3bbe0040a81be24169c512 Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sun, 24 May 2020 18:45:55 -0600 Subject: [PATCH 1/2] Add ignore_emptydoc global option and flags --- sphinx_automodapi/automodapi.py | 21 ++++++++++++++++++--- sphinx_automodapi/automodsumm.py | 29 +++++++++++++++++++++++++++-- 2 files changed, 45 insertions(+), 5 deletions(-) diff --git a/sphinx_automodapi/automodapi.py b/sphinx_automodapi/automodapi.py index 411e7b1..e93b366 100644 --- 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 index 61525eb..b11f4fb 100644 --- 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} From 50b9e1b48bf1b242458718253e227ea99409795a Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sun, 24 May 2020 18:58:54 -0600 Subject: [PATCH 2/2] Only ignore class methods (no obvious use case for funcs/classes) --- sphinx_automodapi/automodapi.py | 15 +++++++-------- sphinx_automodapi/automodsumm.py | 18 ++++++++---------- 2 files changed, 15 insertions(+), 18 deletions(-) diff --git a/sphinx_automodapi/automodapi.py b/sphinx_automodapi/automodapi.py index e93b366..e82eb37 100644 --- a/sphinx_automodapi/automodapi.py +++ b/sphinx_automodapi/automodapi.py @@ -59,10 +59,9 @@ * ``: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. + 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: @@ -333,15 +332,15 @@ 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:') 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 b11f4fb..4136cc9 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -48,10 +48,9 @@ * ``: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. + 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: @@ -70,11 +69,10 @@ class members that are inherited from a base class. This value can be ``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``. + 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 @@ -577,7 +575,7 @@ def get_members_class(obj, typ, include_public=[], continue if ( ignore_emptydoc - and documenter.objtype in ('method', 'class', 'function') + and documenter.objtype == 'method' and not getattr(safe_getattr(obj, name), '__doc__', '') ): continue