Refactor Autosummary directive by DocumenterBridge

CHANGES

@@ -47,6 +47,10 @@ Deprecated
 * ``sphinx.application.Sphinx._setting_up_extension``
 * ``sphinx.config.check_unicode()``
 * ``sphinx.ext.autodoc.importer._MockImporter``
+* ``sphinx.ext.autosummary.Autosummary.warn()``
+* ``sphinx.ext.autosummary.Autosummary.genopt``
+* ``sphinx.ext.autosummary.Autosummary.warnings``
+* ``sphinx.ext.autosummary.Autosummary.result``
 * ``sphinx.ext.doctest.doctest_encode()``
 * ``sphinx.io.SphinxRSTFileInput``
 * ``sphinx.testing.util.remove_unicode_literal()``

doc/extdev/index.rst

@@ -147,7 +147,27 @@ The following is a list of deprecated interfaces.
      - 4.0
      - ``os.path.join()``
 
-   * - ``sphinx.ext.config.check_unicode()``
+   * - ``sphinx.config.check_unicode()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.autosummary.Autosummary.warn()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.autosummary.Autosummary.genopt``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.autosummary.Autosummary.warnings``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.autosummary.Autosummary.result``
      - 2.0
      - 4.0
      - N/A

sphinx/ext/autosummary/__init__.py

@@ -58,6 +58,7 @@ import os
 import posixpath
 import re
 import sys
+import warnings
 from types import ModuleType
 from typing import List, cast
 
@@ -69,6 +70,7 @@ from six import text_type
 
 import sphinx
 from sphinx import addnodes
+from sphinx.deprecation import RemovedInSphinx40Warning
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.ext.autodoc import get_documenters
 from sphinx.ext.autodoc.directive import DocumenterBridge, Options
@@ -234,16 +236,10 @@ class Autosummary(SphinxDirective):
         'template': directives.unchanged,
     }
 
-    def warn(self, msg):
-        # type: (unicode) -> None
-        self.warnings.append(self.state.document.reporter.warning(
-            msg, line=self.lineno))
-
     def run(self):
         # type: () -> List[nodes.Node]
-        self.genopt = Options()
+        self.bridge = DocumenterBridge(self.env, self.state.document.reporter,
-        self.warnings = []  # type: List[nodes.Node]
+                                       Options(), self.lineno)
-        self.result = StringList()
 
         names = [x.strip().split()[0] for x in self.content
                  if x.strip() and re.search(r'^[~a-zA-Z_]', x.strip()[0])]
@@ -276,7 +272,7 @@ class Autosummary(SphinxDirective):
 
             nodes.append(autosummary_toc('', '', tocnode))
 
-        return self.warnings + nodes
+        return nodes
 
     def get_items(self, names):
         # type: (List[unicode]) -> List[Tuple[unicode, unicode, unicode, unicode]]
@@ -302,7 +298,7 @@ class Autosummary(SphinxDirective):
                 items.append((name, '', '', name))
                 continue
 
-            self.result = StringList()  # initialize for each documenter
+            self.bridge.result = StringList()  # initialize for each documenter
             full_name = real_name
             if not isinstance(obj, ModuleType):
                 # give explicitly separated module name, so that members
@@ -310,7 +306,8 @@ class Autosummary(SphinxDirective):
                 full_name = modname + '::' + full_name[len(modname) + 1:]
             # NB. using full_name here is important, since Documenters
             #     handle module prefixes slightly differently
-            documenter = get_documenter(self.env.app, obj, parent)(self, full_name)
+            doccls = get_documenter(self.env.app, obj, parent)
+            documenter = doccls(self.bridge, full_name)
             if not documenter.parse_name():
                 self.warn('failed to parse name %s' % real_name)
                 items.append((display_name, '', '', real_name))
@@ -346,7 +343,7 @@ class Autosummary(SphinxDirective):
             # -- Grab the summary
 
             documenter.add_content(None)
-            summary = extract_summary(self.result.data[:], self.state.document)
+            summary = extract_summary(self.bridge.result.data[:], self.state.document)
 
             items.append((display_name, sig, summary, real_name))
 
@@ -400,6 +397,33 @@ class Autosummary(SphinxDirective):
 
         return [table_spec, table]
 
+    def warn(self, msg):
+        # type: (unicode) -> None
+        warnings.warn('Autosummary.warn() is deprecated',
+                      RemovedInSphinx40Warning, stacklevel=2)
+        logger.warning(msg)
+
+    @property
+    def genopt(self):
+        # type: () -> Options
+        warnings.warn('Autosummary.genopt is deprecated',
+                      RemovedInSphinx40Warning, stacklevel=2)
+        return self.bridge.genopt
+
+    @property
+    def warnings(self):
+        # type: () -> List[nodes.Node]
+        warnings.warn('Autosummary.warnings is deprecated',
+                      RemovedInSphinx40Warning, stacklevel=2)
+        return []
+
+    @property
+    def result(self):
+        # type: () -> StringList
+        warnings.warn('Autosummary.result is deprecated',
+                      RemovedInSphinx40Warning, stacklevel=2)
+        return self.bridge.result
+
 
 def strip_arg_typehint(s):
     # type: (unicode) -> unicode