diff options
Diffstat (limited to 'sphinx/ext/autosummary/generate.py')
| -rw-r--r-- | sphinx/ext/autosummary/generate.py | 69 |
1 files changed, 25 insertions, 44 deletions
diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index 0240d2c7c..d1130d096 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, Callable, Dict, List, NamedTuple, Set, Tuple, Union +from typing import Any, Dict, List, NamedTuple, Set, Tuple, Type, Union from jinja2 import TemplateNotFound from jinja2.sandbox import SandboxedEnvironment @@ -38,7 +38,7 @@ from sphinx import __display_version__, package_dir from sphinx.application import Sphinx from sphinx.builders import Builder from sphinx.config import Config -from sphinx.deprecation import RemovedInSphinx40Warning, RemovedInSphinx50Warning +from sphinx.deprecation import RemovedInSphinx50Warning from sphinx.ext.autodoc import Documenter from sphinx.ext.autodoc.importer import import_module from sphinx.ext.autosummary import get_documenter, import_by_name, import_ivar_by_name @@ -50,11 +50,6 @@ from sphinx.util.inspect import safe_getattr from sphinx.util.osutil import ensuredir from sphinx.util.template import SphinxTemplateLoader -if False: - # For type annotation - from typing import Type # for python3.5.1 - - logger = logging.getLogger(__name__) @@ -64,7 +59,7 @@ class DummyApplication: def __init__(self, translator: NullTranslations) -> None: self.config = Config() self.registry = SphinxComponentRegistry() - self.messagelog = [] # type: List[str] + self.messagelog: List[str] = [] self.srcdir = "/" self.translator = translator self.verbosity = 0 @@ -79,10 +74,11 @@ class DummyApplication: pass -AutosummaryEntry = NamedTuple('AutosummaryEntry', [('name', str), - ('path', str), - ('template', str), - ('recursive', bool)]) +class AutosummaryEntry(NamedTuple): + name: str + path: str + template: str + recursive: bool def setup_documenters(app: Any) -> None: @@ -91,11 +87,11 @@ def setup_documenters(app: Any) -> None: FunctionDocumenter, MethodDocumenter, ModuleDocumenter, NewTypeAttributeDocumenter, NewTypeDataDocumenter, PropertyDocumenter) - documenters = [ + documenters: List[Type[Documenter]] = [ ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter, FunctionDocumenter, MethodDocumenter, NewTypeAttributeDocumenter, NewTypeDataDocumenter, AttributeDocumenter, DecoratorDocumenter, PropertyDocumenter, - ] # type: List[Type[Documenter]] + ] for documenter in documenters: app.registry.add_documenter(documenter.objtype, documenter) @@ -245,8 +241,8 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any, 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] + items: List[str] = [] + public: List[str] = [] for name in dir(obj): try: value = safe_getattr(obj, name) @@ -286,7 +282,7 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any, return public, attrs def get_modules(obj: Any) -> Tuple[List[str], List[str]]: - items = [] # type: List[str] + items: List[str] = [] for _, modname, ispkg in pkgutil.iter_modules(obj.__path__): fullname = name + '.' + modname try: @@ -300,7 +296,7 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any, public = [x for x in items if not x.split('.')[-1].startswith('_')] return public, items - ns = {} # type: Dict[str, Any] + ns: Dict[str, Any] = {} ns.update(context) if doc.objtype == 'module': @@ -352,25 +348,10 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any, def generate_autosummary_docs(sources: List[str], output_dir: str = None, - suffix: str = '.rst', warn: Callable = None, - info: Callable = None, base_path: str = None, + suffix: str = '.rst', base_path: str = None, builder: Builder = None, template_dir: str = None, imported_members: bool = False, app: Any = None, overwrite: bool = True, encoding: str = 'utf-8') -> None: - if info: - warnings.warn('info argument for generate_autosummary_docs() is deprecated.', - RemovedInSphinx40Warning, stacklevel=2) - _info = info - else: - _info = logger.info - - if warn: - warnings.warn('warn argument for generate_autosummary_docs() is deprecated.', - RemovedInSphinx40Warning, stacklevel=2) - _warn = warn - else: - _warn = logger.warning - if builder: warnings.warn('builder argument for generate_autosummary_docs() is deprecated.', RemovedInSphinx50Warning, stacklevel=2) @@ -382,11 +363,11 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None, showed_sources = list(sorted(sources)) if len(showed_sources) > 20: showed_sources = showed_sources[:10] + ['...'] + showed_sources[-10:] - _info(__('[autosummary] generating autosummary for: %s') % - ', '.join(showed_sources)) + logger.info(__('[autosummary] generating autosummary for: %s') % + ', '.join(showed_sources)) if output_dir: - _info(__('[autosummary] writing to %s') % output_dir) + logger.info(__('[autosummary] writing to %s') % output_dir) if base_path is not None: sources = [os.path.join(base_path, filename) for filename in sources] @@ -423,10 +404,10 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None, name, obj, parent, modname = import_ivar_by_name(entry.name) qualname = name.replace(modname + ".", "") except ImportError: - _warn(__('[autosummary] failed to import %r: %s') % (entry.name, e)) + logger.warning(__('[autosummary] failed to import %r: %s') % (entry.name, e)) continue - context = {} + context: Dict[str, Any] = {} if app: context.update(app.config.autosummary_context) @@ -453,8 +434,8 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None, # descend recursively to new files if new_files: generate_autosummary_docs(new_files, output_dir=output_dir, - suffix=suffix, warn=warn, info=info, - base_path=base_path, + suffix=suffix, base_path=base_path, + builder=builder, template_dir=template_dir, imported_members=imported_members, app=app, overwrite=overwrite) @@ -466,7 +447,7 @@ def find_autosummary_in_files(filenames: List[str]) -> List[AutosummaryEntry]: See `find_autosummary_in_lines`. """ - documented = [] # type: List[AutosummaryEntry] + documented: List[AutosummaryEntry] = [] for filename in filenames: with open(filename, encoding='utf-8', errors='ignore') as f: lines = f.read().splitlines() @@ -520,10 +501,10 @@ def find_autosummary_in_lines(lines: List[str], module: str = None, filename: st toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$') template_arg_re = re.compile(r'^\s+:template:\s*(.*?)\s*$') - documented = [] # type: List[AutosummaryEntry] + documented: List[AutosummaryEntry] = [] recursive = False - toctree = None # type: str + toctree: str = None template = None current_module = module in_autosummary = False |