Merge pull request #6817 from tk0miya/6798_autosummary_emits_skip_member_event

Close #6798: autosummary: emit ``autodoc-skip-member`` event on generating stub file

CHANGES

@@ -37,6 +37,7 @@ Features added
 * #6812: Improve a warning message when extensions are not parallel safe
 * #6818: Improve Intersphinx performance for multiple remote inventories.
 * #2546: apidoc: .so file support
+* #6798: autosummary: emit ``autodoc-skip-member`` event on generating stub file
 * #6483: i18n: make explicit titles in toctree translatable
 
 Bugs fixed

doc/usage/extensions/autosummary.rst

@@ -143,6 +143,11 @@ also use these config values:
    The new files will be placed in the directories specified in the
    ``:toctree:`` options of the directives.
 
+   .. versionchanged:: 2.3
+
+      Emits :event:`autodoc-skip-member` event as :mod:`~sphinx.ext.autodoc`
+      does.
+
 .. confval:: autosummary_mock_imports
 
    This value contains a list of modules to be mocked up.  See

sphinx/ext/autosummary/generate.py

@@ -138,9 +138,20 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
         if not template.exists(template_name):
             template_name = 'autosummary/base.rst'
 
+    def skip_member(obj: Any, name: str, objtype: str) -> bool:
+        try:
+            return app.emit_firstresult('autodoc-skip-member', objtype, name,
+                                        obj, False, {})
+        except Exception as exc:
+            logger.warning(__('autosummary: failed to determine %r to be documented.'
+                              'the following exception was raised:\n%s'),
+                           name, exc, type='autosummary')
+            return False
+
     def get_members(obj: Any, types: Set[str], include_public: List[str] = [],
                     imported: bool = True) -> Tuple[List[str], List[str]]:
         items = []  # type: List[str]
+        public = []  # type: List[str]
         for name in dir(obj):
             try:
                 value = safe_getattr(obj, name)
@@ -148,11 +159,20 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                 continue
             documenter = get_documenter(app, value, obj)
             if documenter.objtype in types:
+                # skip imported members if expected
                 if imported or getattr(value, '__module__', None) == obj.__name__:
-                    # skip imported members if expected
-                    items.append(name)
-        public = [x for x in items
-                  if x in include_public or not x.startswith('_')]
+                    skipped = skip_member(value, name, documenter.objtype)
+                    if skipped is True:
+                        pass
+                    elif skipped is False:
+                        # show the member forcedly
+                        items.append(name)
+                        public.append(name)
+                    else:
+                        items.append(name)
+                        if name in include_public or not name.startswith('_'):
+                            # considers member as public
+                            public.append(name)
         return public, items
 
     ns = {}  # type: Dict[str, Any]

tests/roots/test-ext-autosummary-skip-member/conf.py

@@ -0,0 +1,20 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('.'))
+
+
+extensions = ['sphinx.ext.autosummary']
+autosummary_generate = True
+autodoc_default_options = {'members': True}
+
+
+def skip_member(app, what, name, obj, skip, options):
+    if name == 'skipmeth':
+        return True
+    elif name == '_privatemeth':
+        return False
+
+
+def setup(app):
+    app.connect('autodoc-skip-member', skip_member)

tests/roots/test-ext-autosummary-skip-member/index.rst

@@ -0,0 +1,4 @@
+.. autosummary::
+   :toctree: generate
+
+   target.Foo

tests/roots/test-ext-autosummary-skip-member/target.py

@@ -0,0 +1,14 @@
+class Foo:
+    """docstring of Foo."""
+
+    def meth(self):
+        """docstring of meth."""
+        pass
+
+    def skipmeth(self):
+        """docstring of skipmeth."""
+        pass
+
+    def _privatemeth(self):
+        """docstring of _privatemeth."""
+        pass

tests/test_ext_autosummary.py

@@ -36,6 +36,11 @@ default_kw = {
 }
 
 
+@pytest.fixture(scope='function', autouse=True)
+def unload_target_module():
+    sys.modules.pop('target', None)
+
+
 def test_mangle_signature():
     TEST = """
     () :: ()
@@ -304,6 +309,15 @@ def test_generate_autosummary_docs_property(app):
                        ".. autoproperty:: Base.prop")
 
 
+@pytest.mark.sphinx(testroot='ext-autosummary-skip-member')
+def test_autosummary_skip_member(app):
+    app.build()
+
+    content = (app.srcdir / 'generate' / 'target.Foo.rst').text()
+    assert 'Foo.skipmeth' not in content
+    assert 'Foo._privatemeth' in content
+
+
 @pytest.mark.sphinx('dummy', testroot='ext-autosummary',
                     confoverrides={'autosummary_generate': []})
 def test_empty_autosummary_generate(app, status, warning):