diff options
author | Takeshi KOMIYA <i.tkomiya@gmail.com> | 2021-11-25 20:15:43 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-11-25 20:15:43 +0300 |
commit | 15d834e4d892ef008cc2b0bfd33ab90db613b80f (patch) | |
tree | 9f7408f1c62cdf9b47d3bff17224db124ee6d9e1 /sphinx/ext | |
parent | 259de307cac9312e7a2f107d42606185c3aa8426 (diff) | |
parent | 73b7cd51ea29729a41c59d623bf08b32179470f5 (diff) |
Merge pull request #9831 from Yoshanuikabundi/autosummary___all__
Allow autosummary to respect __all__
Diffstat (limited to 'sphinx/ext')
-rw-r--r-- | sphinx/ext/autosummary/__init__.py | 1 | ||||
-rw-r--r-- | sphinx/ext/autosummary/generate.py | 31 |
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, |