diff --git a/CHANGES b/CHANGES index eeda56fc9..86d14de79 100644 --- a/CHANGES +++ b/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()`` diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index eb6416591..f15f92790 100644 --- a/doc/extdev/index.rst +++ b/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 diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index e47c2e1f0..f76ec3ba7 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/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.warnings = [] # type: List[nodes.Node] - self.result = StringList() + self.bridge = DocumenterBridge(self.env, self.state.document.reporter, + Options(), self.lineno) 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