Merge pull request #7526 from tk0miya/refactor_autosummary

refactor: autosummary: Change first argument for AutosummaryRenderer

CHANGES

@@ -12,10 +12,14 @@ Incompatible changes
 Deprecated
 ----------
 
+* The first argument for sphinx.ext.autosummary.generate.AutosummaryRenderer has
+  been changed to Sphinx object
 * The ``template_dir`` argument of ``sphinx.ext.autosummary.generate.
   AutosummaryRenderer``
 * The ``module`` argument of ``sphinx.ext.autosummary.generate.
   find_autosummary_in_docstring()``
+* The ``builder`` argument of ``sphinx.ext.autosummary.generate.
+  generate_autosummary_docs()``
 * The ``template_dir`` argument of ``sphinx.ext.autosummary.generate.
   generate_autosummary_docs()``
 

doc/extdev/deprecated.rst

@@ -26,6 +26,13 @@ The following is a list of deprecated interfaces.
      - (will be) Removed
      - Alternatives
 
+   * - The first argument for
+       ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` has been changed
+       to Sphinx object
+     - 3.1
+     - 5.0
+     - N/A
+
    * - The ``template_dir`` argument of
        ``sphinx.ext.autosummary.generate.AutosummaryRenderer``
      - 3.1
@@ -38,6 +45,12 @@ The following is a list of deprecated interfaces.
      - 5.0
      - N/A
 
+   * - The ``builder`` argument of
+       ``sphinx.ext.autosummary.generate.generate_autosummary_docs()``
+     - 3.1
+     - 5.0
+     - N/A
+
    * - The ``template_dir`` argument of
        ``sphinx.ext.autosummary.generate.generate_autosummary_docs()``
      - 3.1

sphinx/ext/autosummary/generate.py

@@ -27,7 +27,7 @@ import sys
 import warnings
 from gettext import NullTranslations
 from os import path
-from typing import Any, Callable, Dict, List, NamedTuple, Set, Tuple
+from typing import Any, Callable, Dict, List, NamedTuple, Set, Tuple, Union
 
 from jinja2 import TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
@@ -35,6 +35,7 @@ from jinja2.sandbox import SandboxedEnvironment
 import sphinx.locale
 from sphinx import __display_version__
 from sphinx import package_dir
+from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.config import Config
 from sphinx.deprecation import RemovedInSphinx40Warning, RemovedInSphinx50Warning
@@ -60,32 +61,21 @@ class DummyApplication:
     """Dummy Application class for sphinx-autogen command."""
 
     def __init__(self, translator: NullTranslations) -> None:
+        self.config = Config()
         self.registry = SphinxComponentRegistry()
         self.messagelog = []  # type: List[str]
+        self.srcdir = "/"
         self.translator = translator
         self.verbosity = 0
         self._warncount = 0
         self.warningiserror = False
 
+        self.config.init_values()
+
     def emit_firstresult(self, *args: Any) -> None:
         pass
 
 
-class DummyBuilder:
-    """Dummy builder class for sphinx-autogen command."""
-
-    def __init__(self, app: DummyApplication, template_path: str) -> None:
-        if template_path:
-            templates_path = [path.abspath(template_path)]
-        else:
-            templates_path = []
-
-        self.app = app
-        self.srcdir = "/"
-        self.config = Config(overrides={'templates_path': templates_path})
-        self.config.init_values()
-
-
 AutosummaryEntry = NamedTuple('AutosummaryEntry', [('name', str),
                                                    ('path', str),
                                                    ('template', str),
@@ -128,14 +118,17 @@ def _underline(title: str, line: str = '=') -> str:
 class AutosummaryRenderer:
     """A helper class for rendering."""
 
-    def __init__(self, builder: Builder, template_dir: str = None) -> None:
+    def __init__(self, app: Union[Builder, Sphinx], template_dir: str = None) -> None:
+        if isinstance(app, Builder):
+            warnings.warn('The first argument for AutosummaryRenderer has been '
+                          'changed to Sphinx object',
+                          RemovedInSphinx50Warning, stacklevel=2)
         if template_dir:
             warnings.warn('template_dir argument for AutosummaryRenderer is deprecated.',
                           RemovedInSphinx50Warning)
 
         system_templates_path = [os.path.join(package_dir, 'ext', 'autosummary', 'templates')]
-        loader = SphinxTemplateLoader(builder.srcdir,
-                                      builder.config.templates_path,
+        loader = SphinxTemplateLoader(app.srcdir, app.config.templates_path,
                                       system_templates_path)
 
         self.env = SandboxedEnvironment(loader=loader)
@@ -143,10 +136,14 @@ class AutosummaryRenderer:
         self.env.filters['e'] = rst.escape
         self.env.filters['underline'] = _underline
 
-        if builder:
-            if builder.app.translator:
+        if isinstance(app, (Sphinx, DummyApplication)):
+            if app.translator:
                 self.env.add_extension("jinja2.ext.i18n")
-                self.env.install_gettext_translations(builder.app.translator)  # type: ignore
+                self.env.install_gettext_translations(app.translator)  # type: ignore
+        elif isinstance(app, Builder):
+            if app.app.translator:
+                self.env.add_extension("jinja2.ext.i18n")
+                self.env.install_gettext_translations(app.app.translator)  # type: ignore
 
     def exists(self, template_name: str) -> bool:
         """Check if template file exists."""
@@ -282,6 +279,10 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
     else:
         _warn = logger.warning
 
+    if builder:
+        warnings.warn('builder argument for generate_autosummary_docs() is deprecated.',
+                      RemovedInSphinx50Warning)
+
     if template_dir:
         warnings.warn('template_dir argument for generate_autosummary_docs() is deprecated.',
                       RemovedInSphinx50Warning)
@@ -298,7 +299,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
     if base_path is not None:
         sources = [os.path.join(base_path, filename) for filename in sources]
 
-    template = AutosummaryRenderer(builder)
+    template = AutosummaryRenderer(app)
 
     # read
     items = find_autosummary_in_files(sources)
@@ -345,7 +346,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
     if new_files:
         generate_autosummary_docs(new_files, output_dir=output_dir,
                                   suffix=suffix, warn=warn, info=info,
-                                  base_path=base_path, builder=builder,
+                                  base_path=base_path,
                                   imported_members=imported_members, app=app,
                                   overwrite=overwrite)
 
@@ -535,9 +536,12 @@ def main(argv: List[str] = sys.argv[1:]) -> None:
     logging.setup(app, sys.stdout, sys.stderr)  # type: ignore
     setup_documenters(app)
     args = get_parser().parse_args(argv)
-    builder = DummyBuilder(app, args.templates)
+
+    if args.templates:
+        app.config.templates_path.append(path.abspath(args.templates))
+
     generate_autosummary_docs(args.source_file, args.output_dir,
-                              '.' + args.suffix, builder=builder,  # type: ignore
+                              '.' + args.suffix,
                               imported_members=args.imported_members,
                               app=app)