From fe3782d2ed09c957de3fe79b0c5960de6a763c44 Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Sat, 21 Mar 2020 21:44:42 +0900
Subject: [PATCH] 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                            | 1 +
 doc/extdev/deprecated.rst          | 5 +++++
 sphinx/ext/autosummary/__init__.py | 5 +++--
 3 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/CHANGES b/CHANGES
index ecba1c5e5..7ecd7e65e 100644
--- a/CHANGES
+++ b/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()``
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index dc8f9e7b2..9551f8613 100644
--- a/doc/extdev/deprecated.rst
+++ b/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
diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py
index f79b7feb4..9c550c622 100644
--- a/sphinx/ext/autosummary/__init__.py
+++ b/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)