Merge branch '2.0'

1 files changed, 72 insertions, 131 deletions

diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py
index 81c64d445..f5b8fa0f4 100644
--- a/sphinx/builders/html.py
+++ b/sphinx/builders/html.py
@@ -15,16 +15,21 @@ import sys
 import warnings
 from hashlib import md5
 from os import path
+from typing import Any, Dict, IO, Iterable, Iterator, List, Set, Type, Tuple
 
 from docutils import nodes
 from docutils.core import publish_parts
 from docutils.frontend import OptionParser
 from docutils.io import DocTreeInput, StringOutput
+from docutils.nodes import Node
 from docutils.utils import relative_path
 
 from sphinx import package_dir, __display_version__
+from sphinx.application import Sphinx
 from sphinx.builders import Builder
+from sphinx.config import Config
 from sphinx.deprecation import RemovedInSphinx40Warning
+from sphinx.domains import Domain, Index, IndexEntry
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.environment.adapters.indexentries import IndexEntries
 from sphinx.environment.adapters.toctree import TocTree
@@ -41,16 +46,9 @@ from sphinx.util.i18n import format_date
 from sphinx.util.inventory import InventoryFile
 from sphinx.util.matching import patmatch, Matcher, DOTFILES
 from sphinx.util.osutil import os_path, relative_uri, ensuredir, movefile, copyfile
+from sphinx.util.tags import Tags
 from sphinx.writers.html import HTMLWriter, HTMLTranslator
 
-if False:
-    # For type annotation
-    from typing import Any, Dict, IO, Iterable, Iterator, List, Set, Type, Tuple  # NOQA
-    from sphinx.application import Sphinx  # NOQA
-    from sphinx.config import Config  # NOQA
-    from sphinx.domains import Domain, Index, IndexEntry  # NOQA
-    from sphinx.util.tags import Tags  # NOQA
-
 # HTML5 Writer is avialable or not
 if is_html5_writer_available():
     from sphinx.writers.html5 import HTML5Translator
@@ -65,8 +63,7 @@ logger = logging.getLogger(__name__)
 return_codes_re = re.compile('[\r\n]+')
 
 
-def get_stable_hash(obj):
-    # type: (Any) -> str
+def get_stable_hash(obj: Any) -> str:
     """
     Return a stable hash for a Python data structure.  We can't just use
     the md5 of str(obj) since for example dictionary items are enumerated
@@ -89,8 +86,7 @@ class Stylesheet(str):
     attributes = None   # type: Dict[str, str]
     filename = None     # type: str
 
-    def __new__(cls, filename, *args, **attributes):
-        # type: (str, str, str) -> None
+    def __new__(cls, filename: str, *args: str, **attributes: str) -> None:
         self = str.__new__(cls, filename)  # type: ignore
         self.filename = filename
         self.attributes = attributes
@@ -113,8 +109,7 @@ class JavaScript(str):
     attributes = None   # type: Dict[str, str]
     filename = None     # type: str
 
-    def __new__(cls, filename, **attributes):
-        # type: (str, **str) -> None
+    def __new__(cls, filename: str, **attributes: str) -> None:
         self = str.__new__(cls, filename)  # type: ignore
         self.filename = filename
         self.attributes = attributes
@@ -131,8 +126,7 @@ class BuildInfo:
     """
 
     @classmethod
-    def load(cls, f):
-        # type: (IO) -> BuildInfo
+    def load(cls, f: IO) -> "BuildInfo":
         try:
             lines = f.readlines()
             assert lines[0].rstrip() == '# Sphinx build info version 1'
@@ -146,8 +140,7 @@ class BuildInfo:
         except Exception as exc:
             raise ValueError(__('build info file is broken: %r') % exc)
 
-    def __init__(self, config=None, tags=None, config_categories=[]):
-        # type: (Config, Tags, List[str]) -> None
+    def __init__(self, config: Config = None, tags: Tags = None, config_categories: List[str] = []) -> None:  # NOQA
         self.config_hash = ''
         self.tags_hash = ''
 
@@ -158,13 +151,11 @@ class BuildInfo:
         if tags:
             self.tags_hash = get_stable_hash(sorted(tags))
 
-    def __eq__(self, other):  # type: ignore
-        # type: (BuildInfo) -> bool
+    def __eq__(self, other: "BuildInfo") -> bool:  # type: ignore
         return (self.config_hash == other.config_hash and
                 self.tags_hash == other.tags_hash)
 
-    def dump(self, f):
-        # type: (IO) -> None
+    def dump(self, f: IO) -> None:
         f.write('# Sphinx build info version 1\n'
                 '# This file hashes the configuration used when building these files.'
                 ' When it is not found, a full rebuild will be done.\n'
@@ -204,8 +195,7 @@ class StandaloneHTMLBuilder(Builder):
     imgpath = None          # type: str
     domain_indices = []     # type: List[Tuple[str, Type[Index], List[Tuple[str, List[IndexEntry]]], bool]]  # NOQA
 
-    def __init__(self, app):
-        # type: (Sphinx) -> None
+    def __init__(self, app: Sphinx) -> None:
         super().__init__(app)
 
         # CSS files
@@ -214,8 +204,7 @@ class StandaloneHTMLBuilder(Builder):
         # JS files
         self.script_files = []  # type: List[JavaScript]
 
-    def init(self):
-        # type: () -> None
+    def init(self) -> None:
         self.build_info = self.create_build_info()
         # basename of images directory
         self.imagedir = '_images'
@@ -241,12 +230,10 @@ class StandaloneHTMLBuilder(Builder):
 
         self.use_index = self.get_builder_config('use_index', 'html')
 
-    def create_build_info(self):
-        # type: () -> BuildInfo
+    def create_build_info(self) -> BuildInfo:
         return BuildInfo(self.config, self.tags, ['html'])
 
-    def _get_translations_js(self):
-        # type: () -> str
+    def _get_translations_js(self) -> str:
         candidates = [path.join(dir, self.config.language,
                                 'LC_MESSAGES', 'sphinx.js')
                       for dir in self.config.locale_dirs] + \
@@ -260,12 +247,10 @@ class StandaloneHTMLBuilder(Builder):
                 return jsfile
         return None
 
-    def get_theme_config(self):
-        # type: () -> Tuple[str, Dict]
+    def get_theme_config(self) -> Tuple[str, Dict]:
         return self.config.html_theme, self.config.html_theme_options
 
-    def init_templates(self):
-        # type: () -> None
+    def init_templates(self) -> None:
         theme_factory = HTMLThemeFactory(self.app)
         themename, themeoptions = self.get_theme_config()
         self.theme = theme_factory.create(themename)
@@ -273,8 +258,7 @@ class StandaloneHTMLBuilder(Builder):
         self.create_template_bridge()
         self.templates.init(self, self.theme)
 
-    def init_highlighter(self):
-        # type: () -> None
+    def init_highlighter(self) -> None:
         # determine Pygments style and create the highlighter
         if self.config.pygments_style is not None:
             style = self.config.pygments_style
@@ -284,23 +268,20 @@ class StandaloneHTMLBuilder(Builder):
             style = 'sphinx'
         self.highlighter = PygmentsBridge('html', style)
 
-    def init_css_files(self):
-        # type: () -> None
+    def init_css_files(self) -> None:
         for filename, attrs in self.app.registry.css_files:
             self.add_css_file(filename, **attrs)
 
         for filename, attrs in self.get_builder_config('css_files', 'html'):
             self.add_css_file(filename, **attrs)
 
-    def add_css_file(self, filename, **kwargs):
-        # type: (str, **str) -> None
+    def add_css_file(self, filename: str, **kwargs: str) -> None:
         if '://' not in filename:
             filename = posixpath.join('_static', filename)
 
         self.css_files.append(Stylesheet(filename, **kwargs))  # type: ignore
 
-    def init_js_files(self):
-        # type: () -> None
+    def init_js_files(self) -> None:
         self.add_js_file('jquery.js')
         self.add_js_file('underscore.js')
         self.add_js_file('doctools.js')
@@ -315,24 +296,21 @@ class StandaloneHTMLBuilder(Builder):
         if self.config.language and self._get_translations_js():
             self.add_js_file('translations.js')
 
-    def add_js_file(self, filename, **kwargs):
-        # type: (str, **str) -> None
+    def add_js_file(self, filename: str, **kwargs: str) -> None:
         if filename and '://' not in filename:
             filename = posixpath.join('_static', filename)
 
         self.script_files.append(JavaScript(filename, **kwargs))
 
     @property
-    def default_translator_class(self):  # type: ignore
-        # type: () -> Type[nodes.NodeVisitor]
+    def default_translator_class(self) -> Type[nodes.NodeVisitor]:  # type: ignore
         if not html5_ready or self.config.html4_writer:
             return HTMLTranslator
         else:
             return HTML5Translator
 
     @property
-    def math_renderer_name(self):
-        # type: () -> str
+    def math_renderer_name(self) -> str:
         name = self.get_builder_config('math_renderer', 'html')
         if name is not None:
             # use given name
@@ -351,8 +329,7 @@ class StandaloneHTMLBuilder(Builder):
                 # many math_renderers are registered. can't choose automatically!
                 return None
 
-    def get_outdated_docs(self):
-        # type: () -> Iterator[str]
+    def get_outdated_docs(self) -> Iterator[str]:
         try:
             with open(path.join(self.outdir, '.buildinfo')) as fp:
                 buildinfo = BuildInfo.load(fp)
@@ -388,12 +365,10 @@ class StandaloneHTMLBuilder(Builder):
                 # source doesn't exist anymore
                 pass
 
-    def get_asset_paths(self):
-        # type: () -> List[str]
+    def get_asset_paths(self) -> List[str]:
         return self.config.html_extra_path + self.config.html_static_path
 
-    def render_partial(self, node):
-        # type: (nodes.Node) -> Dict[str, str]
+    def render_partial(self, node: Node) -> Dict[str, str]:
         """Utility: Render a lone doctree node."""
         if node is None:
             return {'fragment': ''}
@@ -407,8 +382,7 @@ class StandaloneHTMLBuilder(Builder):
                              settings_overrides={'output_encoding': 'unicode'},
                              source=doc)
 
-    def prepare_writing(self, docnames):
-        # type: (Set[str]) -> None
+    def prepare_writing(self, docnames: Set[str]) -> None:
         # create the search indexer
         self.indexer = None
         if self.search:
@@ -517,8 +491,7 @@ class StandaloneHTMLBuilder(Builder):
                 self.theme.get_options(self.theme_options).items())
         self.globalcontext.update(self.config.html_context)
 
-    def get_doc_context(self, docname, body, metatags):
-        # type: (str, str, str) -> Dict[str, Any]
+    def get_doc_context(self, docname: str, body: str, metatags: str) -> Dict[str, Any]:
         """Collect items for the template context of a page."""
         # find out relations
         prev = next = None
@@ -598,8 +571,7 @@ class StandaloneHTMLBuilder(Builder):
             'page_source_suffix': source_suffix,
         }
 
-    def write_doc(self, docname, doctree):
-        # type: (str, nodes.document) -> None
+    def write_doc(self, docname: str, doctree: nodes.document) -> None:
         destination = StringOutput(encoding='utf-8')
         doctree.settings = self.docsettings
 
@@ -616,16 +588,14 @@ class StandaloneHTMLBuilder(Builder):
         ctx = self.get_doc_context(docname, body, metatags)
         self.handle_page(docname, ctx, event_arg=doctree)
 
-    def write_doc_serialized(self, docname, doctree):
-        # type: (str, nodes.document) -> None
+    def write_doc_serialized(self, docname: str, doctree: nodes.document) -> None:
         self.imgpath = relative_uri(self.get_target_uri(docname), self.imagedir)
         self.post_process_images(doctree)
         title_node = self.env.longtitles.get(docname)
         title = title_node and self.render_partial(title_node)['title'] or ''
         self.index_page(docname, doctree, title)
 
-    def finish(self):
-        # type: () -> None
+    def finish(self) -> None:
         self.finish_tasks.add_task(self.gen_indices)
         self.finish_tasks.add_task(self.gen_additional_pages)
         self.finish_tasks.add_task(self.copy_image_files)
@@ -637,8 +607,7 @@ class StandaloneHTMLBuilder(Builder):
         # dump the search index
         self.handle_finish()
 
-    def gen_indices(self):
-        # type: () -> None
+    def gen_indices(self) -> None:
         logger.info(bold(__('generating indices...')), nonl=True)
 
         # the global general index
@@ -650,8 +619,7 @@ class StandaloneHTMLBuilder(Builder):
 
         logger.info('')
 
-    def gen_additional_pages(self):
-        # type: () -> None
+    def gen_additional_pages(self) -> None:
         # pages from extensions
         for pagelist in self.events.emit('html-collect-pages'):
             for pagename, context, template in pagelist:
@@ -677,8 +645,7 @@ class StandaloneHTMLBuilder(Builder):
 
         logger.info('')
 
-    def write_genindex(self):
-        # type: () -> None
+    def write_genindex(self) -> None:
         # the total count of lines for each index letter, used to distribute
         # the entries into two columns
         genindex = IndexEntries(self.env).create_index(self)
@@ -707,8 +674,7 @@ class StandaloneHTMLBuilder(Builder):
         else:
             self.handle_page('genindex', genindexcontext, 'genindex.html')
 
-    def write_domain_indices(self):
-        # type: () -> None
+    def write_domain_indices(self) -> None:
         for indexname, indexcls, content, collapse in self.domain_indices:
             indexcontext = {
                 'indextitle': indexcls.localname,
@@ -718,8 +684,7 @@ class StandaloneHTMLBuilder(Builder):
             logger.info(' ' + indexname, nonl=True)
             self.handle_page(indexname, indexcontext, 'domainindex.html')
 
-    def copy_image_files(self):
-        # type: () -> None
+    def copy_image_files(self) -> None:
         if self.images:
             stringify_func = ImageAdapter(self.app.env).get_original_image_uri
             ensuredir(path.join(self.outdir, self.imagedir))
@@ -734,11 +699,10 @@ class StandaloneHTMLBuilder(Builder):
                     logger.warning(__('cannot copy image file %r: %s'),
                                    path.join(self.srcdir, src), err)
 
-    def copy_download_files(self):
-        # type: () -> None
-        def to_relpath(f):
-            # type: (str) -> str
+    def copy_download_files(self) -> None:
+        def to_relpath(f: str) -> str:
             return relative_path(self.srcdir, f)
+
         # copy downloadable files
         if self.env.dlfiles:
             ensuredir(path.join(self.outdir, '_downloads'))
@@ -753,8 +717,7 @@ class StandaloneHTMLBuilder(Builder):
                     logger.warning(__('cannot copy downloadable file %r: %s'),
                                    path.join(self.srcdir, src), err)
 
-    def copy_static_files(self):
-        # type: () -> None
+    def copy_static_files(self) -> None:
         try:
             # copy static files
             logger.info(bold(__('copying static files... ')), nonl=True)
@@ -818,8 +781,7 @@ class StandaloneHTMLBuilder(Builder):
         except OSError as err:
             logger.warning(__('cannot copy static file %r'), err)
 
-    def copy_extra_files(self):
-        # type: () -> None
+    def copy_extra_files(self) -> None:
         try:
             # copy html_extra_path files
             logger.info(bold(__('copying extra files... ')), nonl=True)
@@ -836,22 +798,19 @@ class StandaloneHTMLBuilder(Builder):
         except OSError as err:
             logger.warning(__('cannot copy extra file %r'), err)
 
-    def write_buildinfo(self):
-        # type: () -> None
+    def write_buildinfo(self) -> None:
         try:
             with open(path.join(self.outdir, '.buildinfo'), 'w') as fp:
                 self.build_info.dump(fp)
         except OSError as exc:
             logger.warning(__('Failed to write build info file: %r'), exc)
 
-    def cleanup(self):
-        # type: () -> None
+    def cleanup(self) -> None:
         # clean up theme stuff
         if self.theme:
             self.theme.cleanup()
 
-    def post_process_images(self, doctree):
-        # type: (nodes.Node) -> None
+    def post_process_images(self, doctree: Node) -> None:
         """Pick the best candidate for an image and link down-scaled images to
         their high res version.
         """
@@ -876,8 +835,7 @@ class StandaloneHTMLBuilder(Builder):
                 node.replace_self(reference)
                 reference.append(node)
 
-    def load_indexer(self, docnames):
-        # type: (Iterable[str]) -> None
+    def load_indexer(self, docnames: Iterable[str]) -> None:
         keep = set(self.env.all_docs) - set(docnames)
         try:
             searchindexfn = path.join(self.outdir, self.searchindex_filename)
@@ -895,8 +853,7 @@ class StandaloneHTMLBuilder(Builder):
         # delete all entries for files that will be rebuilt
         self.indexer.prune(keep)
 
-    def index_page(self, pagename, doctree, title):
-        # type: (str, nodes.document, str) -> None
+    def index_page(self, pagename: str, doctree: nodes.document, title: str) -> None:
         # only index pages with title
         if self.indexer is not None and title:
             filename = self.env.doc2path(pagename, base=None)
@@ -912,22 +869,19 @@ class StandaloneHTMLBuilder(Builder):
                         indexer_name, indexer_name),
                     RemovedInSphinx40Warning)
 
-    def _get_local_toctree(self, docname, collapse=True, **kwds):
-        # type: (str, bool, Any) -> str
+    def _get_local_toctree(self, docname: str, collapse: bool = True, **kwds) -> str:
         if 'includehidden' not in kwds:
             kwds['includehidden'] = False
         return self.render_partial(TocTree(self.env).get_toctree_for(
             docname, self, collapse, **kwds))['fragment']
 
-    def get_outfilename(self, pagename):
-        # type: (str) -> str
+    def get_outfilename(self, pagename: str) -> str:
         return path.join(self.outdir, os_path(pagename) + self.out_suffix)
 
-    def add_sidebars(self, pagename, ctx):
-        # type: (str, Dict) -> None
-        def has_wildcard(pattern):
-            # type: (str) -> bool
+    def add_sidebars(self, pagename: str, ctx: Dict) -> None:
+        def has_wildcard(pattern: str) -> bool:
             return any(char in pattern for char in '*?[')
+
         sidebars = None
         matched = None
         customsidebar = None
@@ -976,13 +930,11 @@ class StandaloneHTMLBuilder(Builder):
 
     # --------- these are overwritten by the serialization builder
 
-    def get_target_uri(self, docname, typ=None):
-        # type: (str, str) -> str
+    def get_target_uri(self, docname: str, typ: str = None) -> str:
         return docname + self.link_suffix
 
-    def handle_page(self, pagename, addctx, templatename='page.html',
-                    outfilename=None, event_arg=None):
-        # type: (str, Dict, str, str, Any) -> None
+    def handle_page(self, pagename: str, addctx: Dict, templatename: str = 'page.html',
+                    outfilename: str = None, event_arg: Any = None) -> None:
         ctx = self.globalcontext.copy()
         # current_page_name is backwards compatibility
         ctx['pagename'] = ctx['current_page_name'] = pagename
@@ -998,8 +950,7 @@ class StandaloneHTMLBuilder(Builder):
         else:
             ctx['pageurl'] = None
 
-        def pathto(otheruri, resource=False, baseuri=default_baseuri):
-            # type: (str, bool, str) -> str
+        def pathto(otheruri: str, resource: bool = False, baseuri: str = default_baseuri) -> str:  # NOQA
             if resource and '://' in otheruri:
                 # allow non-local resources given by scheme
                 return otheruri
@@ -1011,8 +962,7 @@ class StandaloneHTMLBuilder(Builder):
             return uri
         ctx['pathto'] = pathto
 
-        def css_tag(css):
-            # type: (Stylesheet) -> str
+        def css_tag(css: Stylesheet) -> str:
             attrs = []
             for key in sorted(css.attributes):
                 value = css.attributes[key]
@@ -1022,8 +972,7 @@ class StandaloneHTMLBuilder(Builder):
             return '<link %s />' % ' '.join(attrs)
         ctx['css_tag'] = css_tag
 
-        def hasdoc(name):
-            # type: (str) -> bool
+        def hasdoc(name: str) -> bool:
             if name in self.env.all_docs:
                 return True
             elif name == 'search' and self.search:
@@ -1071,24 +1020,21 @@ class StandaloneHTMLBuilder(Builder):
             ensuredir(path.dirname(source_name))
             copyfile(self.env.doc2path(pagename), source_name)
 
-    def update_page_context(self, pagename, templatename, ctx, event_arg):
-        # type: (str, str, Dict, Any) -> None
+    def update_page_context(self, pagename: str, templatename: str,
+                            ctx: Dict, event_arg: Any) -> None:
         pass
 
-    def handle_finish(self):
-        # type: () -> None
+    def handle_finish(self) -> None:
         if self.indexer:
             self.finish_tasks.add_task(self.dump_search_index)
         self.finish_tasks.add_task(self.dump_inventory)
 
-    def dump_inventory(self):
-        # type: () -> None
+    def dump_inventory(self) -> None:
         logger.info(bold(__('dumping object inventory... ')), nonl=True)
         InventoryFile.dump(path.join(self.outdir, INVENTORY_FILENAME), self.env, self)
         logger.info(__('done'))
 
-    def dump_search_index(self):
-        # type: () -> None
+    def dump_search_index(self) -> None:
         logger.info(
             bold(__('dumping search index in %s ... ') % self.indexer.label()),
             nonl=True)
@@ -1106,8 +1052,7 @@ class StandaloneHTMLBuilder(Builder):
         logger.info(__('done'))
 
 
-def convert_html_css_files(app, config):
-    # type: (Sphinx, Config) -> None
+def convert_html_css_files(app: Sphinx, config: Config) -> None:
     """This converts string styled html_css_files to tuple styled one."""
     html_css_files = []  # type: List[Tuple[str, Dict]]
     for entry in config.html_css_files:
@@ -1124,8 +1069,7 @@ def convert_html_css_files(app, config):
     config.html_css_files = html_css_files  # type: ignore
 
 
-def convert_html_js_files(app, config):
-    # type: (Sphinx, Config) -> None
+def convert_html_js_files(app: Sphinx, config: Config) -> None:
     """This converts string styled html_js_files to tuple styled one."""
     html_js_files = []  # type: List[Tuple[str, Dict]]
     for entry in config.html_js_files:
@@ -1142,16 +1086,15 @@ def convert_html_js_files(app, config):
     config.html_js_files = html_js_files  # type: ignore
 
 
-def setup_js_tag_helper(app, pagename, templatexname, context, doctree):
-    # type: (Sphinx, str, str, Dict, nodes.Node) -> None
+def setup_js_tag_helper(app: Sphinx, pagename: str, templatexname: str,
+                        context: Dict, doctree: Node) -> None:
     """Set up js_tag() template helper.
 
     .. note:: This set up function is added to keep compatibility with webhelper.
     """
     pathto = context.get('pathto')
 
-    def js_tag(js):
-        # type: (JavaScript) -> str
+    def js_tag(js: JavaScript) -> str:
         attrs = []
         body = ''
         if isinstance(js, JavaScript):
@@ -1173,8 +1116,7 @@ def setup_js_tag_helper(app, pagename, templatexname, context, doctree):
     context['js_tag'] = js_tag
 
 
-def validate_math_renderer(app):
-    # type: (Sphinx) -> None
+def validate_math_renderer(app: Sphinx) -> None:
     if app.builder.format != 'html':
         return
 
@@ -1192,8 +1134,7 @@ import sphinx.builders.singlehtml  # NOQA
 import sphinxcontrib.serializinghtml  # NOQA
 
 
-def setup(app):
-    # type: (Sphinx) -> Dict[str, Any]
+def setup(app: Sphinx) -> Dict[str, Any]:
     # builders
     app.add_builder(StandaloneHTMLBuilder)