From 2202bff6b254634491779628ee9de55afe3046dd Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Mon, 16 Mar 2020 01:58:02 +0900
Subject: [PATCH] Deprecate sphinx.ext.autodoc.get_documenters()

---
 CHANGES                            | 1 +
 doc/extdev/deprecated.rst          | 5 +++++
 sphinx/ext/autodoc/__init__.py     | 5 +++--
 sphinx/ext/autodoc/directive.py    | 4 ++--
 sphinx/ext/autosummary/__init__.py | 4 ++--
 5 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/CHANGES b/CHANGES
index d4e8d2ea4..4e40f5d3b 100644
--- a/CHANGES
+++ b/CHANGES
@@ -46,6 +46,7 @@ Deprecated
 * ``sphinx.directives.DescDirective``
 * ``sphinx.domains.std.StandardDomain.add_object()``
 * ``sphinx.domains.python.PyDecoratorMixin``
+* ``sphinx.ext.autodoc.get_documenters()``
 * ``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 cf914a7cd..dc8f9e7b2 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -46,6 +46,11 @@ The following is a list of deprecated interfaces.
      - 5.0
      - N/A
 
+   * - ``sphinx.ext.autodoc.get_documenters()``
+     - 3.0
+     - 5.0
+     - ``sphinx.registry.documenters``
+
    * - ``sphinx.parsers.Parser.app``
      - 3.0
      - 5.0
diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index 92c1e2e9a..f865101bf 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -23,7 +23,7 @@ from docutils.statemachine import StringList
 import sphinx
 from sphinx.application import Sphinx
 from sphinx.config import ENUM
-from sphinx.deprecation import RemovedInSphinx40Warning
+from sphinx.deprecation import RemovedInSphinx40Warning, RemovedInSphinx50Warning
 from sphinx.environment import BuildEnvironment
 from sphinx.ext.autodoc.importer import import_object, get_module_members, get_object_members
 from sphinx.ext.autodoc.mock import mock
@@ -266,7 +266,7 @@ class Documenter:
     @property
     def documenters(self) -> Dict[str, "Type[Documenter]"]:
         """Returns registered Documenter classes"""
-        return get_documenters(self.env.app)
+        return self.env.app.registry.documenters
 
     def add_line(self, line: str, source: str, *lineno: int) -> None:
         """Append one line of generated reST to the output."""
@@ -1713,6 +1713,7 @@ class SlotsAttributeDocumenter(AttributeDocumenter):
 
 def get_documenters(app: Sphinx) -> Dict[str, "Type[Documenter]"]:
     """Returns registered Documenter classes"""
+    warnings.warn("get_documenters() is deprecated.", RemovedInSphinx50Warning)
     return app.registry.documenters
 
 
diff --git a/sphinx/ext/autodoc/directive.py b/sphinx/ext/autodoc/directive.py
index 9302a954a..3be19f089 100644
--- a/sphinx/ext/autodoc/directive.py
+++ b/sphinx/ext/autodoc/directive.py
@@ -18,7 +18,7 @@ from docutils.utils import Reporter, assemble_option_dict
 from sphinx.config import Config
 from sphinx.deprecation import RemovedInSphinx40Warning
 from sphinx.environment import BuildEnvironment
-from sphinx.ext.autodoc import Documenter, Options, get_documenters
+from sphinx.ext.autodoc import Documenter, Options
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective, switch_source_input
 from sphinx.util.nodes import nested_parse_with_titles
@@ -129,7 +129,7 @@ class AutodocDirective(SphinxDirective):
 
         # look up target Documenter
         objtype = self.name[4:]  # strip prefix (auto-).
-        doccls = get_documenters(self.env.app)[objtype]
+        doccls = self.env.app.registry.documenters[objtype]
 
         # process the options with the selected documenter's option_spec
         try:
diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py
index 3d296cbde..f79b7feb4 100644
--- a/sphinx/ext/autosummary/__init__.py
+++ b/sphinx/ext/autosummary/__init__.py
@@ -75,7 +75,7 @@ from sphinx.application import Sphinx
 from sphinx.deprecation import RemovedInSphinx40Warning
 from sphinx.environment import BuildEnvironment
 from sphinx.environment.adapters.toctree import TocTree
-from sphinx.ext.autodoc import Documenter, get_documenters
+from sphinx.ext.autodoc import Documenter
 from sphinx.ext.autodoc.directive import DocumenterBridge, Options
 from sphinx.ext.autodoc.importer import import_module
 from sphinx.ext.autodoc.mock import mock
@@ -203,7 +203,7 @@ def get_documenter(app: Sphinx, obj: Any, parent: Any) -> "Type[Documenter]":
         parent_doc = parent_doc_cls(FakeDirective(), "")
 
     # Get the corrent documenter class for *obj*
-    classes = [cls for cls in get_documenters(app).values()
+    classes = [cls for cls in app.registry.documenters.values()
                if cls.can_document_member(obj, '', False, parent_doc)]
     if classes:
         classes.sort(key=lambda cls: cls.priority)