Merge pull request #9831 from Yoshanuikabundi/autosummary___all__

Allow autosummary to respect __all__

2 files changed, 27 insertions, 5 deletions

diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py
index 478b5c9f3..298c90138 100644
--- a/sphinx/ext/autosummary/__init__.py
+++ b/sphinx/ext/autosummary/__init__.py
@@ -826,5 +826,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('autosummary_mock_imports',
                          lambda config: config.autodoc_mock_imports, 'env')
     app.add_config_value('autosummary_imported_members', [], False, [bool])
+    app.add_config_value('autosummary_ignore_module_all', True, 'env', bool)
 
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py
index a5c8ce11f..87cd0d64e 100644
--- a/sphinx/ext/autosummary/generate.py
+++ b/sphinx/ext/autosummary/generate.py
@@ -28,7 +28,7 @@ import sys
 import warnings
 from gettext import NullTranslations
 from os import path
-from typing import Any, Dict, List, NamedTuple, Set, Tuple, Type, Union
+from typing import Any, Dict, List, NamedTuple, Sequence, Set, Tuple, Type, Union
 
 from jinja2 import TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
@@ -46,7 +46,7 @@ from sphinx.locale import __
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.registry import SphinxComponentRegistry
 from sphinx.util import logging, rst, split_full_qualified_name
-from sphinx.util.inspect import safe_getattr
+from sphinx.util.inspect import getall, safe_getattr
 from sphinx.util.osutil import ensuredir
 from sphinx.util.template import SphinxTemplateLoader
 
@@ -68,6 +68,7 @@ class DummyApplication:
 
         self.config.add('autosummary_context', {}, True, None)
         self.config.add('autosummary_filename_map', {}, True, None)
+        self.config.add('autosummary_ignore_module_all', True, 'env', bool)
         self.config.init_values()
 
     def emit_firstresult(self, *args: Any) -> None:
@@ -192,7 +193,7 @@ class ModuleScanner:
 
     def scan(self, imported_members: bool) -> List[str]:
         members = []
-        for name in dir(self.object):
+        for name in members_of(self.object, self.app.config):
             try:
                 value = safe_getattr(self.object, name)
             except AttributeError:
@@ -212,16 +213,31 @@ class ModuleScanner:
             except AttributeError:
                 imported = False
 
+            respect_module_all = not self.app.config.autosummary_ignore_module_all
             if imported_members:
                 # list all members up
                 members.append(name)
             elif imported is False:
-                # list not-imported members up
+                # list not-imported members
+                members.append(name)
+            elif '__all__' in dir(self.object) and respect_module_all:
+                # list members that have __all__ set
                 members.append(name)
 
         return members
 
 
+def members_of(obj: Any, conf: Config) -> Sequence[str]:
+    """Get the members of ``obj``, possibly ignoring the ``__all__`` module attribute
+
+    Follows the ``conf.autosummary_ignore_module_all`` setting."""
+
+    if conf.autosummary_ignore_module_all:
+        return dir(obj)
+    else:
+        return getall(obj) or dir(obj)
+
+
 def generate_autosummary_content(name: str, obj: Any, parent: Any,
                                  template: AutosummaryRenderer, template_name: str,
                                  imported_members: bool, app: Any,
@@ -245,7 +261,7 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
 
     def get_module_members(obj: Any) -> Dict[str, Any]:
         members = {}
-        for name in dir(obj):
+        for name in members_of(obj, app.config):
             try:
                 members[name] = safe_getattr(obj, name)
             except AttributeError:
@@ -630,6 +646,10 @@ The format of the autosummary directive is documented in the
                         dest='imported_members', default=False,
                         help=__('document imported members (default: '
                                 '%(default)s)'))
+    parser.add_argument('-a', '--respect-module-all', action='store_true',
+                        dest='respect_module_all', default=False,
+                        help=__('document exactly the members in module __all__ attribute. '
+                                '(default: %(default)s)'))
 
     return parser
 
@@ -646,6 +666,7 @@ def main(argv: List[str] = sys.argv[1:]) -> None:
 
     if args.templates:
         app.config.templates_path.append(path.abspath(args.templates))
+    app.config.autosummary_ignore_module_all = not args.respect_module_all  # type: ignore
 
     generate_autosummary_docs(args.source_file, args.output_dir,
                               '.' + args.suffix,