Merge branch '2.0'

3 files changed, 40 insertions, 85 deletions

diff --git a/sphinx/cmd/build.py b/sphinx/cmd/build.py
index 810d69078..d2f6c13b7 100644
--- a/sphinx/cmd/build.py
+++ b/sphinx/cmd/build.py
@@ -14,6 +14,7 @@ import multiprocessing
 import os
 import sys
 import traceback
+from typing import Any, IO, List
 
 from docutils.utils import SystemMessage
 
@@ -26,13 +27,8 @@ from sphinx.util import Tee, format_exception_cut_frames, save_traceback
 from sphinx.util.console import red, nocolor, color_terminal, terminal_safe  # type: ignore
 from sphinx.util.docutils import docutils_namespace, patch_docutils
 
-if False:
-    # For type annotation
-    from typing import Any, IO, List, Union  # NOQA
 
-
-def handle_exception(app, args, exception, stderr=sys.stderr):
-    # type: (Sphinx, Any, Union[Exception, KeyboardInterrupt], IO) -> None
+def handle_exception(app: Sphinx, args: Any, exception: BaseException, stderr: IO = sys.stderr) -> None:  # NOQA
     if args.pdb:
         import pdb
         print(red(__('Exception occurred while building, starting debugger:')),
@@ -82,8 +78,7 @@ def handle_exception(app, args, exception, stderr=sys.stderr):
                   file=stderr)
 
 
-def jobs_argument(value):
-    # type: (str) -> int
+def jobs_argument(value: str) -> int:
     """
     Special type to handle 'auto' flags passed to 'sphinx-build' via -j flag. Can
     be expanded to handle other special scaling requests, such as setting job count
@@ -99,8 +94,7 @@ def jobs_argument(value):
             return jobs
 
 
-def get_parser():
-    # type: () -> argparse.ArgumentParser
+def get_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         usage='%(prog)s [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]',
         epilog=__('For more information, visit <http://sphinx-doc.org/>.'),
@@ -195,15 +189,13 @@ files can be built by specifying individual filenames.
     return parser
 
 
-def make_main(argv=sys.argv[1:]):
-    # type: (List[str]) -> int
+def make_main(argv: List[str] = sys.argv[1:]) -> int:
     """Sphinx build "make mode" entry."""
     from sphinx.cmd import make_mode
     return make_mode.run_make_mode(argv[1:])
 
 
-def build_main(argv=sys.argv[1:]):
-    # type: (List[str]) -> int
+def build_main(argv: List[str] = sys.argv[1:]) -> int:
     """Sphinx build "main" command-line entry."""
 
     parser = get_parser()
@@ -288,8 +280,7 @@ def build_main(argv=sys.argv[1:]):
         return 2
 
 
-def main(argv=sys.argv[1:]):
-    # type: (List[str]) -> int
+def main(argv: List[str] = sys.argv[1:]) -> int:
     sphinx.locale.setlocale(locale.LC_ALL, '')
     sphinx.locale.init_console(os.path.join(package_dir, 'locale'), 'sphinx')
 
diff --git a/sphinx/cmd/make_mode.py b/sphinx/cmd/make_mode.py
index e87aa02fc..508b60959 100644
--- a/sphinx/cmd/make_mode.py
+++ b/sphinx/cmd/make_mode.py
@@ -18,16 +18,13 @@ import os
 import subprocess
 import sys
 from os import path
+from typing import List
 
 import sphinx
 from sphinx.cmd.build import build_main
 from sphinx.util.console import color_terminal, nocolor, bold, blue  # type: ignore
 from sphinx.util.osutil import cd, rmtree
 
-if False:
-    # For type annotation
-    from typing import List  # NOQA
-
 
 BUILDERS = [
     ("",      "html",        "to make standalone HTML files"),
@@ -58,20 +55,16 @@ BUILDERS = [
 
 
 class Make:
-
-    def __init__(self, srcdir, builddir, opts):
-        # type: (str, str, List[str]) -> None
+    def __init__(self, srcdir: str, builddir: str, opts: List[str]) -> None:
         self.srcdir = srcdir
         self.builddir = builddir
         self.opts = opts
         self.makecmd = os.environ.get('MAKE', 'make')  # refer $MAKE to determine make command
 
-    def builddir_join(self, *comps):
-        # type: (str) -> str
+    def builddir_join(self, *comps: str) -> str:
         return path.join(self.builddir, *comps)
 
-    def build_clean(self):
-        # type: () -> int
+    def build_clean(self) -> int:
         srcdir = path.abspath(self.srcdir)
         builddir = path.abspath(self.builddir)
         if not path.exists(self.builddir):
@@ -90,8 +83,7 @@ class Make:
             rmtree(self.builddir_join(item))
         return 0
 
-    def build_help(self):
-        # type: () -> None
+    def build_help(self) -> None:
         if not color_terminal():
             nocolor()
 
@@ -101,8 +93,7 @@ class Make:
             if not osname or os.name == osname:
                 print('  %s  %s' % (blue(bname.ljust(10)), description))
 
-    def build_latexpdf(self):
-        # type: () -> int
+    def build_latexpdf(self) -> int:
         if self.run_generic_build('latex') > 0:
             return 1
 
@@ -117,8 +108,7 @@ class Make:
             print('Error: Failed to run: %s' % makecmd)
             return 1
 
-    def build_latexpdfja(self):
-        # type: () -> int
+    def build_latexpdfja(self) -> int:
         if self.run_generic_build('latex') > 0:
             return 1
 
@@ -133,8 +123,7 @@ class Make:
             print('Error: Failed to run: %s' % makecmd)
             return 1
 
-    def build_info(self):
-        # type: () -> int
+    def build_info(self) -> int:
         if self.run_generic_build('texinfo') > 0:
             return 1
         try:
@@ -144,15 +133,13 @@ class Make:
             print('Error: Failed to run: %s' % self.makecmd)
             return 1
 
-    def build_gettext(self):
-        # type: () -> int
+    def build_gettext(self) -> int:
         dtdir = self.builddir_join('gettext', '.doctrees')
         if self.run_generic_build('gettext', doctreedir=dtdir) > 0:
             return 1
         return 0
 
-    def run_generic_build(self, builder, doctreedir=None):
-        # type: (str, str) -> int
+    def run_generic_build(self, builder: str, doctreedir: str = None) -> int:
         # compatibility with old Makefile
         papersize = os.getenv('PAPER', '')
         opts = self.opts
@@ -168,8 +155,7 @@ class Make:
         return build_main(args + opts)
 
 
-def run_make_mode(args):
-    # type: (List[str]) -> int
+def run_make_mode(args: List[str]) -> int:
     if len(args) < 3:
         print('Error: at least 3 arguments (builder, source '
               'dir, build dir) are required.', file=sys.stderr)
diff --git a/sphinx/cmd/quickstart.py b/sphinx/cmd/quickstart.py
index 778648859..b28cd3519 100644
--- a/sphinx/cmd/quickstart.py
+++ b/sphinx/cmd/quickstart.py
@@ -17,6 +17,7 @@ import time
 import warnings
 from collections import OrderedDict
 from os import path
+from typing import Any, Callable, Dict, List, Pattern, Union
 
 # try to import readline, unix specific enhancement
 try:
@@ -42,10 +43,6 @@ from sphinx.util.console import (  # type: ignore
 from sphinx.util.osutil import ensuredir
 from sphinx.util.template import SphinxRenderer
 
-if False:
-    # For type annotation
-    from typing import Any, Callable, Dict, List, Pattern, Union  # NOQA
-
 TERM_ENCODING = getattr(sys.stdin, 'encoding', None)  # RemovedInSphinx40Warning
 
 EXTENSIONS = OrderedDict([
@@ -82,8 +79,7 @@ else:
 
 
 # function to get input from terminal -- overridden by the test suite
-def term_input(prompt):
-    # type: (str) -> str
+def term_input(prompt: str) -> str:
     if sys.platform == 'win32':
         # Important: On windows, readline is not enabled by default.  In these
         #            environment, escape sequences have been broken.  To avoid the
@@ -98,57 +94,48 @@ class ValidationError(Exception):
     """Raised for validation errors."""
 
 
-def is_path(x):
-    # type: (str) -> str
+def is_path(x: str) -> str:
     x = path.expanduser(x)
     if not path.isdir(x):
         raise ValidationError(__("Please enter a valid path name."))
     return x
 
 
-def allow_empty(x):
-    # type: (str) -> str
+def allow_empty(x: str) -> str:
     return x
 
 
-def nonempty(x):
-    # type: (str) -> str
+def nonempty(x: str) -> str:
     if not x:
         raise ValidationError(__("Please enter some text."))
     return x
 
 
-def choice(*l):
-    # type: (str) -> Callable[[str], str]
-    def val(x):
-        # type: (str) -> str
+def choice(*l: str) -> Callable[[str], str]:
+    def val(x: str) -> str:
         if x not in l:
             raise ValidationError(__('Please enter one of %s.') % ', '.join(l))
         return x
     return val
 
 
-def boolean(x):
-    # type: (str) -> bool
+def boolean(x: str) -> bool:
     if x.upper() not in ('Y', 'YES', 'N', 'NO'):
         raise ValidationError(__("Please enter either 'y' or 'n'."))
     return x.upper() in ('Y', 'YES')
 
 
-def suffix(x):
-    # type: (str) -> str
+def suffix(x: str) -> str:
     if not (x[0:1] == '.' and len(x) > 1):
         raise ValidationError(__("Please enter a file suffix, e.g. '.rst' or '.txt'."))
     return x
 
 
-def ok(x):
-    # type: (str) -> str
+def ok(x: str) -> str:
     return x
 
 
-def term_decode(text):
-    # type: (Union[bytes,str]) -> str
+def term_decode(text: Union[bytes, str]) -> str:
     warnings.warn('term_decode() is deprecated.',
                   RemovedInSphinx40Warning, stacklevel=2)
 
@@ -172,8 +159,7 @@ def term_decode(text):
         return text.decode('latin1')
 
 
-def do_prompt(text, default=None, validator=nonempty):
-    # type: (str, str, Callable[[str], Any]) -> Union[str, bool]
+def do_prompt(text: str, default: str = None, validator: Callable[[str], Any] = nonempty) -> Union[str, bool]:  # NOQA
     while True:
         if default is not None:
             prompt = PROMPT_PREFIX + '%s [%s]: ' % (text, default)
@@ -198,8 +184,7 @@ def do_prompt(text, default=None, validator=nonempty):
     return x
 
 
-def convert_python_source(source, rex=re.compile(r"[uU]('.*?')")):
-    # type: (str, Pattern) -> str
+def convert_python_source(source: str, rex: Pattern = re.compile(r"[uU]('.*?')")) -> str:
     # remove Unicode literal prefixes
     warnings.warn('convert_python_source() is deprecated.',
                   RemovedInSphinx40Warning)
@@ -207,13 +192,11 @@ def convert_python_source(source, rex=re.compile(r"[uU]('.*?')")):
 
 
 class QuickstartRenderer(SphinxRenderer):
-    def __init__(self, templatedir):
-        # type: (str) -> None
+    def __init__(self, templatedir: str) -> None:
         self.templatedir = templatedir or ''
         super().__init__()
 
-    def render(self, template_name, context):
-        # type: (str, Dict) -> str
+    def render(self, template_name: str, context: Dict) -> str:
         user_template = path.join(self.templatedir, path.basename(template_name))
         if self.templatedir and path.exists(user_template):
             return self.render_from_file(user_template, context)
@@ -221,8 +204,7 @@ class QuickstartRenderer(SphinxRenderer):
             return super().render(template_name, context)
 
 
-def ask_user(d):
-    # type: (Dict) -> None
+def ask_user(d: Dict) -> None:
     """Ask the user for quickstart values missing from *d*.
 
     Values are:
@@ -360,8 +342,8 @@ def ask_user(d):
     print()
 
 
-def generate(d, overwrite=True, silent=False, templatedir=None):
-    # type: (Dict, bool, bool, str) -> None
+def generate(d: Dict, overwrite: bool = True, silent: bool = False, templatedir: str = None
+             ) -> None:
     """Generate project based on values in *d*."""
     template = QuickstartRenderer(templatedir=templatedir)
 
@@ -394,8 +376,7 @@ def generate(d, overwrite=True, silent=False, templatedir=None):
     ensuredir(path.join(srcdir, d['dot'] + 'templates'))
     ensuredir(path.join(srcdir, d['dot'] + 'static'))
 
-    def write_file(fpath, content, newline=None):
-        # type: (str, str, str) -> None
+    def write_file(fpath: str, content: str, newline: str = None) -> None:
         if overwrite or not path.isfile(fpath):
             if 'quiet' not in d:
                 print(__('Creating file %s.') % fpath)
@@ -454,8 +435,7 @@ def generate(d, overwrite=True, silent=False, templatedir=None):
     print()
 
 
-def valid_dir(d):
-    # type: (Dict) -> bool
+def valid_dir(d: Dict) -> bool:
     dir = d['path']
     if not path.exists(dir):
         return True
@@ -484,8 +464,7 @@ def valid_dir(d):
     return True
 
 
-def get_parser():
-    # type: () -> argparse.ArgumentParser
+def get_parser() -> argparse.ArgumentParser:
     description = __(
         "\n"
         "Generate required files for a Sphinx project.\n"
@@ -568,8 +547,7 @@ def get_parser():
     return parser
 
 
-def main(argv=sys.argv[1:]):
-    # type: (List[str]) -> int
+def main(argv: List[str] = sys.argv[1:]) -> int:
     sphinx.locale.setlocale(locale.LC_ALL, '')
     sphinx.locale.init_console(os.path.join(package_dir, 'locale'), 'sphinx')