Deprecate sphinx.ext.autodoc.add_documenter() and AutoDirective._register

CHANGES

@@ -21,6 +21,8 @@ Deprecated
   values will be accepted at 2.0.
 * ``format_annotation()`` and ``formatargspec()`` is deprecated.  Please use
   ``sphinx.util.inspect.Signature`` instead.
+* ``sphinx.ext.autodoc.add_documenter()`` and ``AutoDirective._register`` is now
+  deprecated.  Please use ``app.add_autodocumenter()``
 
 Features added
 --------------

sphinx/application.py

@@ -642,9 +642,9 @@ class Sphinx(object):
     def add_autodocumenter(self, cls):
         # type: (Any) -> None
         logger.debug('[app] adding autodocumenter: %r', cls)
-        from sphinx.ext import autodoc
+        from sphinx.ext.autodoc import AutoDirective
-        autodoc.add_documenter(cls)
+        self.add_directive('auto' + cls.objtype, AutoDirective)
-        self.add_directive('auto' + cls.objtype, autodoc.AutoDirective)
+        self.registry.add_documenter(cls.objtype, cls)
 
     def add_autodoc_attrgetter(self, type, getter):
         # type: (Any, Callable) -> None

sphinx/ext/autodoc/__init__.py

@@ -14,6 +14,7 @@
 import re
 import sys
 import inspect
+import warnings
 
 from six import iterkeys, iteritems, itervalues, text_type, class_types, string_types
 
@@ -23,6 +24,7 @@ from docutils.parsers.rst import Directive
 from docutils.statemachine import ViewList
 
 import sphinx
+from sphinx.deprecation import RemovedInSphinx20Warning
 from sphinx.ext.autodoc.importer import mock, import_object
 from sphinx.ext.autodoc.importer import _MockImporter  # to keep compatibility  # NOQA
 from sphinx.ext.autodoc.inspector import format_annotation, formatargspec  # to keep compatibility  # NOQA
@@ -323,6 +325,14 @@ class Documenter(object):
         # the module analyzer to get at attribute docs, or None
         self.analyzer = None        # type: Any
 
+    @property
+    def documenters(self):
+        # type: () -> Dict[unicode, Type[Documenter]]
+        """Returns registered Documenter classes"""
+        classes = dict(AutoDirective._registry)  # registered directly
+        classes.update(self.env.app.registry.documenters)  # registered by API
+        return classes
+
     def add_line(self, line, source, *lineno):
         # type: (unicode, unicode, int) -> None
         """Append one line of generated reST to the output."""
@@ -727,7 +737,7 @@ class Documenter(object):
         # document non-skipped members
         memberdocumenters = []  # type: List[Tuple[Documenter, bool]]
         for (mname, member, isattr) in self.filter_members(members, want_all):
-            classes = [cls for cls in itervalues(AutoDirective._registry)
+            classes = [cls for cls in itervalues(self.documenters)
                        if cls.can_document_member(member, mname, isattr, self)]
             if not classes:
                 # don't know how to document this member
@@ -1463,11 +1473,28 @@ class InstanceAttributeDocumenter(AttributeDocumenter):
         AttributeDocumenter.add_content(self, more_content, no_docstring=True)
 
 
+class DeprecatedDict(dict):
+    def __init__(self, message):
+        self.message = message
+        super(DeprecatedDict, self).__init__()
+
+    def __setitem__(self, key, value):
+        warnings.warn(self.message, RemovedInSphinx20Warning)
+        super(DeprecatedDict, self).__setitem__(key, value)
+
+    def setdefault(self, key, default=None):
+        warnings.warn(self.message, RemovedInSphinx20Warning)
+        super(DeprecatedDict, self).setdefault(key, default)
+
+    def update(self, other=None):
+        warnings.warn(self.message, RemovedInSphinx20Warning)
+        super(DeprecatedDict, self).update(other)
+
+
 class AutoDirective(Directive):
     """
     The AutoDirective class is used for all autodoc directives.  It dispatches
-    most of the work to one of the Documenters, which it selects through its
+    most of the work to one of the Documenters.
-    *_registry* dictionary.
 
     The *_special_attrgetters* attribute is used to customize ``getattr()``
     calls that the Documenters make; its entries are of the form ``type:
@@ -1478,8 +1505,11 @@ class AutoDirective(Directive):
     dictionary should include all necessary functions for accessing
     attributes of the parents.
     """
-    # a registry of objtype -> documenter class
+    # a registry of objtype -> documenter class (Deprecated)
-    _registry = {}  # type: Dict[unicode, Type[Documenter]]
+    _registry = DeprecatedDict(
+        'AutoDirective._registry has been deprecated. '
+        'Please use app.add_autodocumenter() instead.'
+    )  # type: Dict[unicode, Type[Documenter]]
 
     # a registry of type -> getattr function
     _special_attrgetters = {}  # type: Dict[Type, Callable]
@@ -1521,7 +1551,7 @@ class AutoDirective(Directive):
 
         # find out what documenter to call
         objtype = self.name[4:]
-        doc_class = self._registry[objtype]
+        doc_class = get_documenters(self.env.app)[objtype]
         # add default flags
         for flag in self._default_flags:
             if flag not in doc_class.option_spec:
@@ -1575,6 +1605,10 @@ class AutoDirective(Directive):
 def add_documenter(cls):
     # type: (Type[Documenter]) -> None
     """Register a new Documenter."""
+    warnings.warn('sphinx.ext.autodoc.add_documenter() has been deprecated. '
+                  'Please use app.add_autodocumenter() instead.',
+                  RemovedInSphinx20Warning)
+
     if not issubclass(cls, Documenter):
         raise ExtensionError('autodoc documenter %r must be a subclass '
                              'of Documenter' % cls)
@@ -1585,6 +1619,15 @@ def add_documenter(cls):
     AutoDirective._registry[cls.objtype] = cls
 
 
+def get_documenters(app):
+    # type: (Sphinx) -> Dict[unicode, Type[Documenter]]
+    """Returns registered Documenter classes"""
+    classes = dict(AutoDirective._registry)  # registered directly
+    if app:
+        classes.update(app.registry.documenters)  # registered by API
+    return classes
+
+
 def setup(app):
     # type: (Sphinx) -> Dict[unicode, Any]
     app.add_autodocumenter(ModuleDocumenter)

sphinx/ext/autosummary/__init__.py

@@ -72,8 +72,8 @@ from sphinx import addnodes
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.util import import_object, rst, logging
 from sphinx.pycode import ModuleAnalyzer, PycodeError
-from sphinx.ext.autodoc import Options
 from sphinx.ext.autodoc.importer import import_module
+from sphinx.ext.autodoc import Options, get_documenters
 
 if False:
     # For type annotation
@@ -158,8 +158,8 @@ class FakeDirective(object):
     genopt = Options()
 
 
-def get_documenter(obj, parent):
+def get_documenter(app, obj, parent):
-    # type: (Any, Any) -> Type[Documenter]
+    # type: (Sphinx, Any, Any) -> Type[Documenter]
     """Get an autodoc.Documenter class suitable for documenting the given
     object.
 
@@ -167,8 +167,7 @@ def get_documenter(obj, parent):
     another Python object (e.g. a module or a class) to which *obj*
     belongs to.
     """
-    from sphinx.ext.autodoc import AutoDirective, DataDocumenter, \
+    from sphinx.ext.autodoc import DataDocumenter, ModuleDocumenter
-        ModuleDocumenter
 
     if inspect.ismodule(obj):
         # ModuleDocumenter.can_document_member always returns False
@@ -176,7 +175,7 @@ def get_documenter(obj, parent):
 
     # Construct a fake documenter for *parent*
     if parent is not None:
-        parent_doc_cls = get_documenter(parent, None)
+        parent_doc_cls = get_documenter(app, parent, None)
     else:
         parent_doc_cls = ModuleDocumenter
 
@@ -186,7 +185,7 @@ def get_documenter(obj, parent):
         parent_doc = parent_doc_cls(FakeDirective(), "")
 
     # Get the corrent documenter class for *obj*
-    classes = [cls for cls in AutoDirective._registry.values()
+    classes = [cls for cls in get_documenters(app).values()
                if cls.can_document_member(obj, '', False, parent_doc)]
     if classes:
         classes.sort(key=lambda cls: cls.priority)
@@ -289,7 +288,7 @@ class Autosummary(Directive):
                 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(obj, parent)(self, full_name)
+            documenter = get_documenter(self.env.app, obj, parent)(self, full_name)
             if not documenter.parse_name():
                 self.warn('failed to parse name %s' % real_name)
                 items.append((display_name, '', '', real_name))
@@ -615,7 +614,8 @@ def process_generate_options(app):
 
     generate_autosummary_docs(genfiles, builder=app.builder,
                               warn=logger.warning, info=logger.info,
-                              suffix=suffix, base_path=app.srcdir)
+                              suffix=suffix, base_path=app.srcdir,
+                              app=app)
 
 
 def setup(app):

sphinx/ext/autosummary/generate.py

@@ -31,26 +31,13 @@ from jinja2.sandbox import SandboxedEnvironment
 
 from sphinx import __display_version__
 from sphinx import package_dir
+from sphinx.ext.autodoc import add_documenter
 from sphinx.ext.autosummary import import_by_name, get_documenter
 from sphinx.jinja2glue import BuiltinTemplateLoader
 from sphinx.util.osutil import ensuredir
 from sphinx.util.inspect import safe_getattr
 from sphinx.util.rst import escape as rst_escape
 
-# Add documenters to AutoDirective registry
-from sphinx.ext.autodoc import add_documenter, \
-    ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter, \
-    FunctionDocumenter, MethodDocumenter, AttributeDocumenter, \
-    InstanceAttributeDocumenter
-add_documenter(ModuleDocumenter)
-add_documenter(ClassDocumenter)
-add_documenter(ExceptionDocumenter)
-add_documenter(DataDocumenter)
-add_documenter(FunctionDocumenter)
-add_documenter(MethodDocumenter)
-add_documenter(AttributeDocumenter)
-add_documenter(InstanceAttributeDocumenter)
-
 if False:
     # For type annotation
     from typing import Any, Callable, Dict, Tuple, List  # NOQA
@@ -60,6 +47,22 @@ if False:
     from sphinx.environment import BuildEnvironment  # NOQA
 
 
+def setup_documenters():
+    from sphinx.ext.autodoc import (
+        ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter,
+        FunctionDocumenter, MethodDocumenter, AttributeDocumenter,
+        InstanceAttributeDocumenter
+    )
+    add_documenter(ModuleDocumenter)
+    add_documenter(ClassDocumenter)
+    add_documenter(ExceptionDocumenter)
+    add_documenter(DataDocumenter)
+    add_documenter(FunctionDocumenter)
+    add_documenter(MethodDocumenter)
+    add_documenter(AttributeDocumenter)
+    add_documenter(InstanceAttributeDocumenter)
+
+
 def _simple_info(msg):
     # type: (unicode) -> None
     print(msg)
@@ -81,7 +84,7 @@ def _underline(title, line='='):
 def generate_autosummary_docs(sources, output_dir=None, suffix='.rst',
                               warn=_simple_warn, info=_simple_info,
                               base_path=None, builder=None, template_dir=None,
-                              imported_members=False):
+                              imported_members=False, app=None):
     # type: (List[unicode], unicode, unicode, Callable, Callable, unicode, Builder, unicode, bool) -> None  # NOQA
 
     showed_sources = list(sorted(sources))
@@ -148,7 +151,7 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst',
         new_files.append(fn)
 
         with open(fn, 'w') as f:
-            doc = get_documenter(obj, parent)
+            doc = get_documenter(app, obj, parent)
 
             if template_name is not None:
                 template = template_env.get_template(template_name)
@@ -167,7 +170,7 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst',
                         value = safe_getattr(obj, name)
                     except AttributeError:
                         continue
-                    documenter = get_documenter(value, obj)
+                    documenter = get_documenter(app, value, obj)
                     if documenter.objtype == typ:
                         if typ == 'method':
                             items.append(name)
@@ -392,6 +395,7 @@ The format of the autosummary directive is documented in the
 
 def main(argv=sys.argv[1:]):
     # type: (List[str]) -> None
+    setup_documenters()
     args = get_parser().parse_args(argv)
     generate_autosummary_docs(args.source_file, args.output_dir,
                               '.' + args.suffix,

sphinx/registry.py

@@ -38,6 +38,7 @@ if False:
     from sphinx.builders import Builder  # NOQA
     from sphinx.domains import Domain, Index  # NOQA
     from sphinx.environment import BuildEnvironment  # NOQA
+    from sphinx.ext.autodoc import Documenter  # NOQA
     from sphinx.util.typing import RoleFunction  # NOQA
 
 logger = logging.getLogger(__name__)
@@ -52,6 +53,7 @@ EXTENSION_BLACKLIST = {
 class SphinxComponentRegistry(object):
     def __init__(self):
         self.builders = {}              # type: Dict[unicode, Type[Builder]]
+        self.documenters = {}           # type: Dict[unicode, Type[Documenter]]
         self.domains = {}               # type: Dict[unicode, Type[Domain]]
         self.domain_directives = {}     # type: Dict[unicode, Dict[unicode, Any]]
         self.domain_indices = {}        # type: Dict[unicode, List[Type[Index]]]
@@ -284,6 +286,10 @@ class SphinxComponentRegistry(object):
         # type: () -> List[Type[Transform]]
         return self.post_transforms
 
+    def add_documenter(self, objtype, documenter):
+        # type: (unicode, Type[Documenter]) -> None
+        self.documenters[objtype] = documenter
+
     def load_extension(self, app, extname):
         # type: (Sphinx, unicode) -> None
         """Load a Sphinx extension."""

tests/py35/test_autodoc_py35.py

@@ -112,7 +112,7 @@ def skip_member(app, what, name, obj, skip, options):
 @pytest.mark.usefixtures('setup_test')
 def test_generate():
     def assert_warns(warn_str, objtype, name, **kw):
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.generate(**kw)
         assert len(directive.result) == 0, directive.result
         assert len(_warnings) == 1, _warnings
@@ -120,7 +120,7 @@ def test_generate():
         del _warnings[:]
 
     def assert_works(objtype, name, **kw):
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.generate(**kw)
         assert directive.result
         # print '\n'.join(directive.result)
@@ -134,7 +134,7 @@ def test_generate():
         assert set(processed_docstrings) | set(processed_signatures) == set(items)
 
     def assert_result_contains(item, objtype, name, **kw):
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.generate(**kw)
         # print '\n'.join(directive.result)
         assert len(_warnings) == 0, _warnings
@@ -142,7 +142,7 @@ def test_generate():
         del directive.result[:]
 
     def assert_order(items, objtype, name, member_order, **kw):
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.options.member_order = member_order
         inst.generate(**kw)
         assert len(_warnings) == 0, _warnings

tests/test_autodoc.py

@@ -121,7 +121,7 @@ def skip_member(app, what, name, obj, skip, options):
 @pytest.mark.usefixtures('setup_test')
 def test_parse_name():
     def verify(objtype, name, result):
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         assert inst.parse_name()
         assert (inst.modname, inst.objpath, inst.args, inst.retann) == result
 
@@ -164,7 +164,7 @@ def test_parse_name():
 @pytest.mark.usefixtures('setup_test')
 def test_format_signature():
     def formatsig(objtype, name, obj, args, retann):
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.fullname = name
         inst.doc_as_attr = False  # for class objtype
         inst.object = obj
@@ -270,7 +270,7 @@ def test_format_signature():
 @pytest.mark.usefixtures('setup_test')
 def test_get_doc():
     def getdocl(objtype, obj, encoding=None):
-        inst = AutoDirective._registry[objtype](directive, 'tmp')
+        inst = app.registry.documenters[objtype](directive, 'tmp')
         inst.object = obj
         inst.objpath = [obj.__name__]
         inst.doc_as_attr = False
@@ -449,7 +449,7 @@ def test_get_doc():
 @pytest.mark.usefixtures('setup_test')
 def test_docstring_processing():
     def process(objtype, name, obj):
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.object = obj
         inst.fullname = name
         return list(inst.process_doc(inst.get_doc()))
@@ -506,7 +506,7 @@ def test_docstring_property_processing():
     def genarate_docstring(objtype, name, **kw):
         del processed_docstrings[:]
         del processed_signatures[:]
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.generate(**kw)
         results = list(directive.result)
         docstrings = inst.get_doc()[0]
@@ -555,7 +555,7 @@ def test_new_documenter():
     add_documenter(MyDocumenter)
 
     def assert_result_contains(item, objtype, name, **kw):
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.generate(**kw)
         # print '\n'.join(directive.result)
         assert len(_warnings) == 0, _warnings
@@ -581,7 +581,7 @@ def test_attrgetter_using():
         AutoDirective._special_attrgetters[type] = special_getattr
 
         del getattr_spy[:]
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.generate(**kw)
 
         hooked_members = [s[1] for s in getattr_spy]
@@ -603,7 +603,7 @@ def test_attrgetter_using():
 @pytest.mark.usefixtures('setup_test')
 def test_generate():
     def assert_warns(warn_str, objtype, name, **kw):
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.generate(**kw)
         assert len(directive.result) == 0, directive.result
         assert len(_warnings) == 1, _warnings
@@ -611,7 +611,7 @@ def test_generate():
         del _warnings[:]
 
     def assert_works(objtype, name, **kw):
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.generate(**kw)
         assert directive.result
         # print '\n'.join(directive.result)
@@ -625,7 +625,7 @@ def test_generate():
         assert set(processed_docstrings) | set(processed_signatures) == set(items)
 
     def assert_result_contains(item, objtype, name, **kw):
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.generate(**kw)
         # print '\n'.join(directive.result)
         assert len(_warnings) == 0, _warnings
@@ -633,7 +633,7 @@ def test_generate():
         del directive.result[:]
 
     def assert_order(items, objtype, name, member_order, **kw):
-        inst = AutoDirective._registry[objtype](directive, name)
+        inst = app.registry.documenters[objtype](directive, name)
         inst.options.member_order = member_order
         inst.generate(**kw)
         assert len(_warnings) == 0, _warnings

tests/test_ext_autosummary.py

@@ -57,10 +57,14 @@ def test_mangle_signature():
 
 
 @pytest.mark.sphinx('dummy', **default_kw)
-def test_get_items_summary(app, status, warning):
+def test_get_items_summary(make_app, app_params):
+    import sphinx.ext.autosummary
+    import sphinx.ext.autosummary.generate
+    sphinx.ext.autosummary.generate.setup_documenters()
+    args, kwargs = app_params
+    app = make_app(*args, **kwargs)
     # monkey-patch Autosummary.get_items so we can easily get access to it's
     # results..
-    import sphinx.ext.autosummary
     orig_get_items = sphinx.ext.autosummary.Autosummary.get_items
 
     autosummary_items = {}
@@ -81,7 +85,7 @@ def test_get_items_summary(app, status, warning):
     finally:
         sphinx.ext.autosummary.Autosummary.get_items = orig_get_items
 
-    html_warnings = warning.getvalue()
+    html_warnings = app._warning.getvalue()
     assert html_warnings == ''
 
     expected_values = {

tests/test_templating.py

@@ -10,10 +10,14 @@
 """
 
 import pytest
+from sphinx.ext.autosummary.generate import setup_documenters
 
 
 @pytest.mark.sphinx('html', testroot='templating')
-def test_layout_overloading(app, status, warning):
+def test_layout_overloading(make_app, app_params):
+    setup_documenters()
+    args, kwargs = app_params
+    app = make_app(*args, **kwargs)
     app.builder.build_update()
 
     result = (app.outdir / 'contents.html').text(encoding='utf-8')
@@ -22,7 +26,10 @@ def test_layout_overloading(app, status, warning):
 
 
 @pytest.mark.sphinx('html', testroot='templating')
-def test_autosummary_class_template_overloading(app, status, warning):
+def test_autosummary_class_template_overloading(make_app, app_params):
+    setup_documenters()
+    args, kwargs = app_params
+    app = make_app(*args, **kwargs)
     app.builder.build_update()
 
     result = (app.outdir / 'generated' / 'sphinx.application.TemplateBridge.html').text(