Merge branch '2.0'

1 files changed, 67 insertions, 90 deletions

diff --git a/sphinx/registry.py b/sphinx/registry.py
index 51c240b0e..d2f9da3a1 100644
--- a/sphinx/registry.py
+++ b/sphinx/registry.py
@@ -11,36 +11,37 @@
 import traceback
 from importlib import import_module
 from types import MethodType
+from typing import Any, Callable, Dict, Iterator, List, Tuple, Union
 
+from docutils import nodes
+from docutils.io import Input
+from docutils.nodes import Element, Node, TextElement
+from docutils.parsers import Parser
 from docutils.parsers.rst import Directive
+from docutils.transforms import Transform
 from pkg_resources import iter_entry_points
 
-from sphinx.domains import ObjType
+from sphinx.builders import Builder
+from sphinx.config import Config
+from sphinx.deprecation import RemovedInSphinx30Warning
+from sphinx.domains import Domain, Index, ObjType
 from sphinx.domains.std import GenericObject, Target
+from sphinx.environment import BuildEnvironment
 from sphinx.errors import ExtensionError, SphinxError, VersionRequirementError
 from sphinx.extension import Extension
+from sphinx.io import SphinxFileInput
 from sphinx.locale import __
 from sphinx.parsers import Parser as SphinxParser
 from sphinx.roles import XRefRole
 from sphinx.util import logging
 from sphinx.util.logging import prefixed_warnings
+from sphinx.util.typing import RoleFunction, TitleGetter
 
 if False:
     # For type annotation
-    from typing import Any, Callable, Dict, Iterator, List, Tuple, Union  # NOQA
     from typing import Type  # for python3.5.1
-    from docutils import nodes  # NOQA
-    from docutils.io import Input  # NOQA
-    from docutils.parsers import Parser  # NOQA
-    from docutils.transforms import Transform  # NOQA
-    from sphinx.application import Sphinx  # NOQA
-    from sphinx.builders import Builder  # NOQA
-    from sphinx.config import Config  # NOQA
-    from sphinx.domains import Domain, Index  # NOQA
-    from sphinx.environment import BuildEnvironment  # NOQA
-    from sphinx.ext.autodoc import Documenter  # NOQA
-    from sphinx.io import SphinxFileInput  # NOQA
-    from sphinx.util.typing import RoleFunction, TitleGetter  # NOQA
+    from sphinx.application import Sphinx
+    from sphinx.ext.autodoc import Documenter
 
 logger = logging.getLogger(__name__)
 
@@ -52,8 +53,7 @@ EXTENSION_BLACKLIST = {
 
 
 class SphinxComponentRegistry:
-    def __init__(self):
-        # type: () -> None
+    def __init__(self) -> None:
         #: special attrgetter for autodoc; class object -> attrgetter
         self.autodoc_attrgettrs = {}    # type: Dict[Type, Callable[[Any, str, Any], Any]]
 
@@ -87,7 +87,7 @@ class SphinxComponentRegistry:
 
         #: additional enumerable nodes
         #: a dict of node class -> tuple of figtype and title_getter function
-        self.enumerable_nodes = {}      # type: Dict[Type[nodes.Node], Tuple[str, TitleGetter]]
+        self.enumerable_nodes = {}      # type: Dict[Type[Node], Tuple[str, TitleGetter]]
 
         #: HTML inline and block math renderers
         #: a dict of name -> tuple of visit function and depart function
@@ -122,8 +122,7 @@ class SphinxComponentRegistry:
         #: additional transforms; list of transforms
         self.transforms = []            # type: List[Type[Transform]]
 
-    def add_builder(self, builder, override=False):
-        # type: (Type[Builder], bool) -> None
+    def add_builder(self, builder: "Type[Builder]", override: bool = False) -> None:
         logger.debug('[app] adding builder: %r', builder)
         if not hasattr(builder, 'name'):
             raise ExtensionError(__('Builder class %s has no "name" attribute') % builder)
@@ -132,8 +131,7 @@ class SphinxComponentRegistry:
                                  (builder.name, self.builders[builder.name].__module__))
         self.builders[builder.name] = builder
 
-    def preload_builder(self, app, name):
-        # type: (Sphinx, str) -> None
+    def preload_builder(self, app: "Sphinx", name: str) -> None:
         if name is None:
             return
 
@@ -147,26 +145,22 @@ class SphinxComponentRegistry:
 
             self.load_extension(app, entry_point.module_name)
 
-    def create_builder(self, app, name):
-        # type: (Sphinx, str) -> Builder
+    def create_builder(self, app: "Sphinx", name: str) -> Builder:
         if name not in self.builders:
             raise SphinxError(__('Builder name %s not registered') % name)
 
         return self.builders[name](app)
 
-    def add_domain(self, domain, override=False):
-        # type: (Type[Domain], bool) -> None
+    def add_domain(self, domain: "Type[Domain]", override: bool = False) -> None:
         logger.debug('[app] adding domain: %r', domain)
         if domain.name in self.domains and not override:
             raise ExtensionError(__('domain %s already registered') % domain.name)
         self.domains[domain.name] = domain
 
-    def has_domain(self, domain):
-        # type: (str) -> bool
+    def has_domain(self, domain: str) -> bool:
         return domain in self.domains
 
-    def create_domains(self, env):
-        # type: (BuildEnvironment) -> Iterator[Domain]
+    def create_domains(self, env: BuildEnvironment) -> Iterator[Domain]:
         for DomainClass in self.domains.values():
             domain = DomainClass(env)
 
@@ -179,8 +173,8 @@ class SphinxComponentRegistry:
 
             yield domain
 
-    def add_directive_to_domain(self, domain, name, cls, override=False):
-        # type: (str, str, Type[Directive], bool) -> None
+    def add_directive_to_domain(self, domain: str, name: str,
+                                cls: "Type[Directive]", override: bool = False) -> None:
         logger.debug('[app] adding directive to domain: %r', (domain, name, cls))
         if domain not in self.domains:
             raise ExtensionError(__('domain %s not yet registered') % domain)
@@ -191,8 +185,9 @@ class SphinxComponentRegistry:
                                  (name, domain))
         directives[name] = cls
 
-    def add_role_to_domain(self, domain, name, role, override=False):
-        # type: (str, str, Union[RoleFunction, XRefRole], bool) -> None
+    def add_role_to_domain(self, domain: str, name: str,
+                           role: Union[RoleFunction, XRefRole], override: bool = False
+                           ) -> None:
         logger.debug('[app] adding role to domain: %r', (domain, name, role))
         if domain not in self.domains:
             raise ExtensionError(__('domain %s not yet registered') % domain)
@@ -202,8 +197,8 @@ class SphinxComponentRegistry:
                                  (name, domain))
         roles[name] = role
 
-    def add_index_to_domain(self, domain, index, override=False):
-        # type: (str, Type[Index], bool) -> None
+    def add_index_to_domain(self, domain: str, index: "Type[Index]",
+                            override: bool = False) -> None:
         logger.debug('[app] adding index to domain: %r', (domain, index))
         if domain not in self.domains:
             raise ExtensionError(__('domain %s not yet registered') % domain)
@@ -213,10 +208,10 @@ class SphinxComponentRegistry:
                                  (index.name, domain))
         indices.append(index)
 
-    def add_object_type(self, directivename, rolename, indextemplate='',
-                        parse_node=None, ref_nodeclass=None, objname='',
-                        doc_field_types=[], override=False):
-        # type: (str, str, str, Callable, Type[nodes.TextElement], str, List, bool) -> None
+    def add_object_type(self, directivename: str, rolename: str, indextemplate: str = '',
+                        parse_node: Callable = None, ref_nodeclass: "Type[TextElement]" = None,
+                        objname: str = '', doc_field_types: List = [], override: bool = False
+                        ) -> None:
         logger.debug('[app] adding object type: %r',
                      (directivename, rolename, indextemplate, parse_node,
                       ref_nodeclass, objname, doc_field_types))
@@ -237,9 +232,9 @@ class SphinxComponentRegistry:
                                  directivename)
         object_types[directivename] = ObjType(objname or directivename, rolename)
 
-    def add_crossref_type(self, directivename, rolename, indextemplate='',
-                          ref_nodeclass=None, objname='', override=False):
-        # type: (str, str, str, Type[nodes.TextElement], str, bool) -> None
+    def add_crossref_type(self, directivename: str, rolename: str, indextemplate: str = '',
+                          ref_nodeclass: "Type[TextElement]" = None, objname: str = '',
+                          override: bool = False) -> None:
         logger.debug('[app] adding crossref type: %r',
                      (directivename, rolename, indextemplate, ref_nodeclass, objname))
 
@@ -257,17 +252,16 @@ class SphinxComponentRegistry:
                                  directivename)
         object_types[directivename] = ObjType(objname or directivename, rolename)
 
-    def add_source_suffix(self, suffix, filetype, override=False):
-        # type: (str, str, bool) -> None
+    def add_source_suffix(self, suffix: str, filetype: str, override: bool = False) -> None:
         logger.debug('[app] adding source_suffix: %r, %r', suffix, filetype)
         if suffix in self.source_suffix and not override:
             raise ExtensionError(__('source_suffix %r is already registered') % suffix)
         else:
             self.source_suffix[suffix] = filetype
 
-    def add_source_parser(self, parser, **kwargs):
-        # type: (Type[Parser], bool) -> None
+    def add_source_parser(self, parser: "Type[Parser]", **kwargs) -> None:
         logger.debug('[app] adding search source_parser: %r', parser)
+
         # create a map from filetype to parser
         for filetype in parser.supported:
             if filetype in self.source_parsers and not kwargs.get('override'):
@@ -276,27 +270,23 @@ class SphinxComponentRegistry:
             else:
                 self.source_parsers[filetype] = parser
 
-    def get_source_parser(self, filetype):
-        # type: (str) -> Type[Parser]
+    def get_source_parser(self, filetype: str) -> "Type[Parser]":
         try:
             return self.source_parsers[filetype]
         except KeyError:
             raise SphinxError(__('Source parser for %s not registered') % filetype)
 
-    def get_source_parsers(self):
-        # type: () -> Dict[str, Type[Parser]]
+    def get_source_parsers(self) -> Dict[str, "Type[Parser]"]:
         return self.source_parsers
 
-    def create_source_parser(self, app, filename):
-        # type: (Sphinx, str) -> Parser
+    def create_source_parser(self, app: "Sphinx", filename: str) -> Parser:
         parser_class = self.get_source_parser(filename)
         parser = parser_class()
         if isinstance(parser, SphinxParser):
             parser.set_application(app)
         return parser
 
-    def get_source_input(self, filetype):
-        # type: (str) -> Type[Input]
+    def get_source_input(self, filetype: str) -> "Type[Input]":
         try:
             return self.source_inputs[filetype]
         except KeyError:
@@ -306,15 +296,14 @@ class SphinxComponentRegistry:
             except KeyError:
                 return None
 
-    def add_translator(self, name, translator, override=False):
-        # type: (str, Type[nodes.NodeVisitor], bool) -> None
+    def add_translator(self, name: str, translator: "Type[nodes.NodeVisitor]",
+                       override: bool = False) -> None:
         logger.debug('[app] Change of translator for the %s builder.' % name)
         if name in self.translators and not override:
             raise ExtensionError(__('Translator for %r already exists') % name)
         self.translators[name] = translator
 
-    def add_translation_handlers(self, node, **kwargs):
-        # type: (Type[nodes.Element], Any) -> None
+    def add_translation_handlers(self, node: "Type[Element]", **kwargs) -> None:
         logger.debug('[app] adding translation_handlers: %r, %r', node, kwargs)
         for builder_name, handlers in kwargs.items():
             translation_handlers = self.translation_handlers.setdefault(builder_name, {})
@@ -325,13 +314,11 @@ class SphinxComponentRegistry:
                 raise ExtensionError(__('kwargs for add_node() must be a (visit, depart) '
                                         'function tuple: %r=%r') % builder_name, handlers)
 
-    def get_translator_class(self, builder):
-        # type: (Builder) -> Type[nodes.NodeVisitor]
+    def get_translator_class(self, builder: Builder) -> "Type[nodes.NodeVisitor]":
         return self.translators.get(builder.name,
                                     builder.default_translator_class)
 
-    def create_translator(self, builder, *args):
-        # type: (Builder, Any) -> nodes.NodeVisitor
+    def create_translator(self, builder: Builder, *args) -> nodes.NodeVisitor:
         translator_class = self.get_translator_class(builder)
         assert translator_class, "translator not found for %s" % builder.name
         translator = translator_class(*args)
@@ -349,54 +336,48 @@ class SphinxComponentRegistry:
 
         return translator
 
-    def add_transform(self, transform):
-        # type: (Type[Transform]) -> None
+    def add_transform(self, transform: "Type[Transform]") -> None:
         logger.debug('[app] adding transform: %r', transform)
         self.transforms.append(transform)
 
-    def get_transforms(self):
-        # type: () -> List[Type[Transform]]
+    def get_transforms(self) -> List["Type[Transform]"]:
         return self.transforms
 
-    def add_post_transform(self, transform):
-        # type: (Type[Transform]) -> None
+    def add_post_transform(self, transform: "Type[Transform]") -> None:
         logger.debug('[app] adding post transform: %r', transform)
         self.post_transforms.append(transform)
 
-    def get_post_transforms(self):
-        # type: () -> List[Type[Transform]]
+    def get_post_transforms(self) -> List["Type[Transform]"]:
         return self.post_transforms
 
-    def add_documenter(self, objtype, documenter):
-        # type: (str, Type[Documenter]) -> None
+    def add_documenter(self, objtype: str, documenter: "Type[Documenter]") -> None:
         self.documenters[objtype] = documenter
 
-    def add_autodoc_attrgetter(self, typ, attrgetter):
-        # type: (Type, Callable[[Any, str, Any], Any]) -> None
+    def add_autodoc_attrgetter(self, typ: "Type",
+                               attrgetter: Callable[[Any, str, Any], Any]) -> None:
         self.autodoc_attrgettrs[typ] = attrgetter
 
     def add_css_files(self, filename, **attributes):
         self.css_files.append((filename, attributes))
 
-    def add_js_file(self, filename, **attributes):
-        # type: (str, **str) -> None
+    def add_js_file(self, filename: str, **attributes: str) -> None:
         logger.debug('[app] adding js_file: %r, %r', filename, attributes)
         self.js_files.append((filename, attributes))
 
-    def add_latex_package(self, name, options):
-        # type: (str, str) -> None
+    def add_latex_package(self, name: str, options: str) -> None:
         logger.debug('[app] adding latex package: %r', name)
         self.latex_packages.append((name, options))
 
-    def add_enumerable_node(self, node, figtype, title_getter=None, override=False):
-        # type: (Type[nodes.Node], str, TitleGetter, bool) -> None
+    def add_enumerable_node(self, node: "Type[Node]", figtype: str,
+                            title_getter: TitleGetter = None, override: bool = False) -> None:
         logger.debug('[app] adding enumerable node: (%r, %r, %r)', node, figtype, title_getter)
         if node in self.enumerable_nodes and not override:
             raise ExtensionError(__('enumerable_node %r already registered') % node)
         self.enumerable_nodes[node] = (figtype, title_getter)
 
-    def add_html_math_renderer(self, name, inline_renderers, block_renderers):
-        # type: (str, Tuple[Callable, Callable], Tuple[Callable, Callable]) -> None
+    def add_html_math_renderer(self, name: str,
+                               inline_renderers: Tuple[Callable, Callable],
+                               block_renderers: Tuple[Callable, Callable]) -> None:
         logger.debug('[app] adding html_math_renderer: %s, %r, %r',
                      name, inline_renderers, block_renderers)
         if name in self.html_inline_math_renderers:
@@ -405,8 +386,7 @@ class SphinxComponentRegistry:
         self.html_inline_math_renderers[name] = inline_renderers
         self.html_block_math_renderers[name] = block_renderers
 
-    def load_extension(self, app, extname):
-        # type: (Sphinx, str) -> None
+    def load_extension(self, app: "Sphinx", extname: str) -> None:
         """Load a Sphinx extension."""
         if extname in app.extensions:  # alread loaded
             return
@@ -451,8 +431,7 @@ class SphinxComponentRegistry:
 
             app.extensions[extname] = Extension(extname, mod, **metadata)
 
-    def get_envversion(self, app):
-        # type: (Sphinx) -> Dict[str, str]
+    def get_envversion(self, app: "Sphinx") -> Dict[str, str]:
         from sphinx.environment import ENV_VERSION
         envversion = {ext.name: ext.metadata['env_version'] for ext in app.extensions.values()
                       if ext.metadata.get('env_version')}
@@ -460,8 +439,7 @@ class SphinxComponentRegistry:
         return envversion
 
 
-def merge_source_suffix(app, config):
-    # type: (Sphinx, Config) -> None
+def merge_source_suffix(app: "Sphinx", config: Config) -> None:
     """Merge source_suffix which specified by user and added by extensions."""
     for suffix, filetype in app.registry.source_suffix.items():
         if suffix not in app.config.source_suffix:
@@ -475,8 +453,7 @@ def merge_source_suffix(app, config):
     app.registry.source_suffix = app.config.source_suffix
 
 
-def setup(app):
-    # type: (Sphinx) -> Dict[str, Any]
+def setup(app: "Sphinx") -> Dict[str, Any]:
     app.connect('config-inited', merge_source_suffix)
 
     return {