mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge pull request #6535 from tk0miya/refactor_type_annotation_cmd
Migrate to py3 style type annotation: sphinx.cmd
This commit is contained in:
Takeshi KOMIYA
GitHub
commit
05949f8347
@ -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')
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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([
|
||||
@ -84,8 +81,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
|
||||
@ -100,58 +96,49 @@ 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)
|
||||
|
||||
@ -175,8 +162,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)
|
||||
@ -201,8 +187,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)
|
||||
@ -210,13 +195,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)
|
||||
@ -224,8 +207,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:
|
||||
@ -367,8 +349,8 @@ directly.'''))
|
||||
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)
|
||||
|
||||
@ -401,8 +383,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)
|
||||
@ -460,8 +441,7 @@ where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
|
||||
'''))
|
||||
|
||||
|
||||
def valid_dir(d):
|
||||
# type: (Dict) -> bool
|
||||
def valid_dir(d: Dict) -> bool:
|
||||
dir = d['path']
|
||||
if not path.exists(dir):
|
||||
return True
|
||||
@ -490,8 +470,7 @@ def valid_dir(d):
|
||||
return True
|
||||
|
||||
|
||||
def get_parser():
|
||||
# type: () -> argparse.ArgumentParser
|
||||
def get_parser() -> argparse.ArgumentParser:
|
||||
parser = argparse.ArgumentParser(
|
||||
usage='%(prog)s [OPTIONS] <PROJECT_DIR>',
|
||||
epilog=__("For more information, visit <http://sphinx-doc.org/>."),
|
||||
@ -572,8 +551,7 @@ Makefile to be used with sphinx-build.
|
||||
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')
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user