autosummary: Fix compatibility of get_documenter() API (refs: #4366)

CHANGES

@@ -10,6 +10,9 @@ Incompatible changes
 Deprecated
 ----------
 
+* autosummary: The interface of ``sphinx.ext.autosummary.get_documenter()`` has
+  been changed (Since 1.7.0)
+
 Features added
 --------------
 
@@ -22,6 +25,8 @@ Bugs fixed
 * #4622: epub: :confval:`epub_scheme` does not effect to content.opf
 * #4627: graphviz: Fit graphviz images to page
 * #4617: quickstart: PROJECT_DIR argument is required
+* autosummary: The interface of ``sphinx.ext.autosummary.get_documenter()`` has
+  been changed
 
 Testing
 --------

sphinx/application.py

@@ -88,6 +88,7 @@ builtin_extensions = (
     'sphinx.roles',
     'sphinx.transforms.post_transforms',
     'sphinx.transforms.post_transforms.images',
+    'sphinx.util.compat',
     # collectors should be loaded by specific order
     'sphinx.environment.collectors.dependencies',
     'sphinx.environment.collectors.asset',

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 TYPE_CHECKING
 
@@ -69,6 +70,7 @@ from six import text_type
 
 import sphinx
 from sphinx import addnodes
+from sphinx.deprecation import RemovedInSphinx20Warning
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.ext.autodoc import get_documenters
 from sphinx.ext.autodoc.directive import DocumenterBridge, Options
@@ -153,13 +155,17 @@ def autosummary_table_visit_html(self, node):
 
 # -- autodoc integration -------------------------------------------------------
 
+# current application object (used in `get_documenter()`).
+_app = None  # type: Sphinx
+
+
 class FakeDirective(DocumenterBridge):
     def __init__(self):
         super(FakeDirective, self).__init__({}, None, Options(), 0)  # type: ignore
 
 
-def get_documenter(app, obj, parent):
-    # type: (Sphinx, Any, Any) -> Type[Documenter]
+def get_documenter(*args):
+    # type: (Any) -> Type[Documenter]
     """Get an autodoc.Documenter class suitable for documenting the given
     object.
 
@@ -168,6 +174,16 @@ def get_documenter(app, obj, parent):
     belongs to.
     """
     from sphinx.ext.autodoc import DataDocumenter, ModuleDocumenter
+    if len(args) == 3:
+        # new style arguments: (app, obj, parent)
+        app, obj, parent = args
+    else:
+        # old style arguments: (obj, parent)
+        app = _app
+        obj, parent = args
+        warnings.warn('the interface of get_documenter() has been changed. '
+                      'Please give application object as first argument.',
+                      RemovedInSphinx20Warning)
 
     if inspect.ismodule(obj):
         # ModuleDocumenter.can_document_member always returns False

sphinx/util/compat.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.util.compat
+    ~~~~~~~~~~~~~~~~~~
+
+    modules for backward compatibility
+
+    :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import sys
+
+
+if False:
+    # For type annotation
+    from typing import Any, Dict  # NOQA
+    from sphinx.application import Sphinx  # NOQA
+
+
+def register_application_for_autosummary(app):
+    # type: (Sphinx) -> None
+    """Register application object to autosummary module.
+
+    Since Sphinx-1.7, documenters and attrgetters are registered into
+    applicaiton object.  As a result, the arguments of
+    ``get_documenter()`` has been changed.  To keep compatibility,
+    this handler registers application object to the module.
+    """
+    if 'sphinx.ext.autosummary' in sys.modules:
+        from sphinx.ext import autosummary
+        autosummary._app = app
+
+
+def setup(app):
+    # type: (Sphinx) -> Dict[unicode, Any]
+    app.connect('builder-inited', register_application_for_autosummary)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }