Deprecate sphinx.ext.autosummary:process_autosummary_toc()

The handler searches autosummary_toc node under root of document and
just under section nodes.  But that is already done in
ToctreeCollector.process_doc().  So it's no longer needed.

CHANGES

@@ -54,6 +54,7 @@ Deprecated
 * ``sphinx.domains.std.StandardDomain.add_object()``
 * ``sphinx.domains.python.PyDecoratorMixin``
 * ``sphinx.ext.autodoc.get_documenters()``
+* ``sphinx.ext.autosummary.process_autosummary_toc()``
 * ``sphinx.parsers.Parser.app``
 * ``sphinx.testing.path.Path.text()``
 * ``sphinx.testing.path.Path.bytes()``

doc/extdev/deprecated.rst

@@ -51,6 +51,11 @@ The following is a list of deprecated interfaces.
      - 5.0
      - ``sphinx.registry.documenters``
 
+   * - ``sphinx.ext.autosummary.process_autosummary_toc()``
+     - 3.0
+     - 5.0
+     - N/A
+
    * - ``sphinx.parsers.Parser.app``
      - 3.0
      - 5.0

sphinx/ext/autosummary/__init__.py

@@ -72,7 +72,7 @@ from docutils.statemachine import StringList
 import sphinx
 from sphinx import addnodes
 from sphinx.application import Sphinx
-from sphinx.deprecation import RemovedInSphinx40Warning
+from sphinx.deprecation import RemovedInSphinx40Warning, RemovedInSphinx50Warning
 from sphinx.environment import BuildEnvironment
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.ext.autodoc import Documenter
@@ -110,6 +110,8 @@ def process_autosummary_toc(app: Sphinx, doctree: nodes.document) -> None:
     """Insert items described in autosummary:: to the TOC tree, but do
     not generate the toctree:: list.
     """
+    warnings.warn('process_autosummary_toc() is deprecated',
+                  RemovedInSphinx50Warning, stacklevel=2)
     env = app.builder.env
     crawled = {}
 
@@ -766,7 +768,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
                  texinfo=(autosummary_noop, autosummary_noop))
     app.add_directive('autosummary', Autosummary)
     app.add_role('autolink', AutoLink())
-    app.connect('doctree-read', process_autosummary_toc)
     app.connect('builder-inited', process_generate_options)
     app.add_config_value('autosummary_generate', [], True, [bool])
     app.add_config_value('autosummary_generate_overwrite', True, False)