diff options
Diffstat (limited to 'sphinx/application.py')
| -rw-r--r-- | sphinx/application.py | 108 |
1 files changed, 38 insertions, 70 deletions
diff --git a/sphinx/application.py b/sphinx/application.py index c7b293828..4735beffd 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -14,11 +14,10 @@ import os import pickle import platform import sys -import warnings from collections import deque from io import StringIO from os import path -from typing import IO, Any, Callable, Dict, List, Optional, Tuple, Union +from typing import IO, TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple, Type, Union from docutils import nodes from docutils.nodes import Element, TextElement @@ -30,14 +29,13 @@ from pygments.lexer import Lexer import sphinx from sphinx import locale, package_dir from sphinx.config import Config -from sphinx.deprecation import RemovedInSphinx40Warning from sphinx.domains import Domain, Index from sphinx.environment import BuildEnvironment from sphinx.environment.collectors import EnvironmentCollector from sphinx.errors import ApplicationError, ConfigError, VersionRequirementError from sphinx.events import EventManager from sphinx.extension import Extension -from sphinx.highlighting import lexer_classes, lexers +from sphinx.highlighting import lexer_classes from sphinx.locale import __ from sphinx.project import Project from sphinx.registry import SphinxComponentRegistry @@ -52,10 +50,7 @@ from sphinx.util.osutil import abspath, ensuredir, relpath from sphinx.util.tags import Tags from sphinx.util.typing import RoleFunction, TitleGetter -if False: - # For type annotation - from typing import Type # for python3.5.1 - +if TYPE_CHECKING: from docutils.nodes import Node # NOQA from sphinx.builders import Builder @@ -135,6 +130,9 @@ class Sphinx: :ivar outdir: Directory for storing build documents. """ + warningiserror: bool + _warncount: int + def __init__(self, srcdir: str, confdir: Optional[str], outdir: str, doctreedir: str, buildername: str, confoverrides: Dict = None, status: IO = sys.stdout, warning: IO = sys.stderr, @@ -142,12 +140,12 @@ class Sphinx: verbosity: int = 0, parallel: int = 0, keep_going: bool = False) -> None: self.phase = BuildPhase.INITIALIZATION self.verbosity = verbosity - self.extensions = {} # type: Dict[str, Extension] - self.builder = None # type: Builder - self.env = None # type: BuildEnvironment - self.project = None # type: Project + self.extensions: Dict[str, Extension] = {} + self.builder: Builder = None + self.env: BuildEnvironment = None + self.project: Project = None self.registry = SphinxComponentRegistry() - self.html_themes = {} # type: Dict[str, str] + self.html_themes: Dict[str, str] = {} # validate provided directories self.srcdir = abspath(srcdir) @@ -175,14 +173,14 @@ class Sphinx: self.parallel = parallel if status is None: - self._status = StringIO() # type: IO + self._status: IO = StringIO() self.quiet = True else: self._status = status self.quiet = False if warning is None: - self._warning = StringIO() # type: IO + self._warning: IO = StringIO() else: self._warning = warning self._warncount = 0 @@ -197,7 +195,7 @@ class Sphinx: # keep last few messages for traceback # This will be filled by sphinx.util.logging.LastMessagesWriter - self.messagelog = deque(maxlen=10) # type: deque + self.messagelog: deque = deque(maxlen=10) # say hello to the world logger.info(bold(__('Running Sphinx v%s') % sphinx.__display_version__)) @@ -294,7 +292,7 @@ class Sphinx: if catalog.domain == 'sphinx' and catalog.is_outdated(): catalog.write_mo(self.config.language) - locale_dirs = list(repo.locale_dirs) # type: List[Optional[str]] + locale_dirs: List[Optional[str]] = list(repo.locale_dirs) locale_dirs += [None] locale_dirs += [path.join(package_dir, 'locale')] @@ -445,7 +443,7 @@ class Sphinx: self.events.disconnect(listener_id) def emit(self, event: str, *args: Any, - allowed_exceptions: Tuple["Type[Exception]", ...] = ()) -> List: + allowed_exceptions: Tuple[Type[Exception], ...] = ()) -> List: """Emit *event* and pass *arguments* to the callback functions. Return the return values of all callbacks as a list. Do not emit core @@ -462,7 +460,7 @@ class Sphinx: return self.events.emit(event, *args, allowed_exceptions=allowed_exceptions) def emit_firstresult(self, event: str, *args: Any, - allowed_exceptions: Tuple["Type[Exception]", ...] = ()) -> Any: + allowed_exceptions: Tuple[Type[Exception], ...] = ()) -> Any: """Emit *event* and pass *arguments* to the callback functions. Return the result of the first callback that doesn't return ``None``. @@ -481,7 +479,7 @@ class Sphinx: # registering addon parts - def add_builder(self, builder: "Type[Builder]", override: bool = False) -> None: + def add_builder(self, builder: Type["Builder"], override: bool = False) -> None: """Register a new builder. :param builder: A builder class @@ -528,8 +526,7 @@ class Sphinx: ``'env'``) to a string. However, booleans are still accepted and converted internally. """ - logger.debug('[app] adding config value: %r', - (name, default, rebuild) + ((types,) if types else ())) + logger.debug('[app] adding config value: %r', (name, default, rebuild, types)) if rebuild in (False, True): rebuild = 'env' if rebuild else '' self.config.add(name, default, rebuild, types) @@ -544,7 +541,7 @@ class Sphinx: logger.debug('[app] adding event: %r', name) self.events.add(name) - def set_translator(self, name: str, translator_class: "Type[nodes.NodeVisitor]", + def set_translator(self, name: str, translator_class: Type[nodes.NodeVisitor], override: bool = False) -> None: """Register or override a Docutils translator class. @@ -563,7 +560,7 @@ class Sphinx: """ self.registry.add_translator(name, translator_class, override=override) - def add_node(self, node: "Type[Element]", override: bool = False, + def add_node(self, node: Type[Element], override: bool = False, **kwargs: Tuple[Callable, Optional[Callable]]) -> None: """Register a Docutils node class. @@ -607,7 +604,7 @@ class Sphinx: docutils.register_node(node) self.registry.add_translation_handlers(node, **kwargs) - def add_enumerable_node(self, node: "Type[Element]", figtype: str, + def add_enumerable_node(self, node: Type[Element], figtype: str, title_getter: TitleGetter = None, override: bool = False, **kwargs: Tuple[Callable, Callable]) -> None: """Register a Docutils node class as a numfig target. @@ -636,7 +633,7 @@ class Sphinx: self.registry.add_enumerable_node(node, figtype, title_getter, override=override) self.add_node(node, override=override, **kwargs) - def add_directive(self, name: str, cls: "Type[Directive]", override: bool = False) -> None: + def add_directive(self, name: str, cls: Type[Directive], override: bool = False) -> None: """Register a Docutils directive. :param name: The name of directive @@ -726,7 +723,7 @@ class Sphinx: role = roles.GenericRole(name, nodeclass) docutils.register_role(name, role) - def add_domain(self, domain: "Type[Domain]", override: bool = False) -> None: + def add_domain(self, domain: Type[Domain], override: bool = False) -> None: """Register a domain. :param domain: A domain class @@ -740,7 +737,7 @@ class Sphinx: self.registry.add_domain(domain, override=override) def add_directive_to_domain(self, domain: str, name: str, - cls: "Type[Directive]", override: bool = False) -> None: + cls: Type[Directive], override: bool = False) -> None: """Register a Docutils directive in a domain. Like :meth:`add_directive`, but the directive is added to the domain @@ -777,7 +774,7 @@ class Sphinx: """ self.registry.add_role_to_domain(domain, name, role, override=override) - def add_index_to_domain(self, domain: str, index: "Type[Index]", override: bool = False + def add_index_to_domain(self, domain: str, index: Type[Index], override: bool = False ) -> None: """Register a custom index for a domain. @@ -795,7 +792,7 @@ class Sphinx: self.registry.add_index_to_domain(domain, index) def add_object_type(self, directivename: str, rolename: str, indextemplate: str = '', - parse_node: Callable = None, ref_nodeclass: "Type[TextElement]" = None, + parse_node: Callable = None, ref_nodeclass: Type[TextElement] = None, objname: str = '', doc_field_types: List = [], override: bool = False ) -> None: """Register a new object type. @@ -862,7 +859,7 @@ class Sphinx: override=override) def add_crossref_type(self, directivename: str, rolename: str, indextemplate: str = '', - ref_nodeclass: "Type[TextElement]" = None, objname: str = '', + ref_nodeclass: Type[TextElement] = None, objname: str = '', override: bool = False) -> None: """Register a new crossref object type. @@ -900,7 +897,7 @@ class Sphinx: indextemplate, ref_nodeclass, objname, override=override) - def add_transform(self, transform: "Type[Transform]") -> None: + def add_transform(self, transform: Type[Transform]) -> None: """Register a Docutils transform to be applied after parsing. Add the standard docutils :class:`Transform` subclass *transform* to @@ -935,7 +932,7 @@ class Sphinx: """ # NOQA self.registry.add_transform(transform) - def add_post_transform(self, transform: "Type[Transform]") -> None: + def add_post_transform(self, transform: Type[Transform]) -> None: """Register a Docutils transform to be applied before writing. Add the standard docutils :class:`Transform` subclass *transform* to @@ -946,13 +943,6 @@ class Sphinx: """ self.registry.add_post_transform(transform) - def add_javascript(self, filename: str, **kwargs: Any) -> None: - """An alias of :meth:`add_js_file`.""" - warnings.warn('The app.add_javascript() is deprecated. ' - 'Please use app.add_js_file() instead.', - RemovedInSphinx40Warning, stacklevel=2) - self.add_js_file(filename, **kwargs) - def add_js_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None: """Register a JavaScript file to include in the HTML output. @@ -1032,6 +1022,8 @@ class Sphinx: * - Priority - Main purpose in Sphinx + * - 200 + - default priority for built-in CSS files * - 500 - default priority for extensions * - 800 @@ -1061,24 +1053,6 @@ class Sphinx: if hasattr(self.builder, 'add_css_file'): self.builder.add_css_file(filename, priority=priority, **kwargs) # type: ignore - def add_stylesheet(self, filename: str, alternate: bool = False, title: str = None - ) -> None: - """An alias of :meth:`add_css_file`.""" - warnings.warn('The app.add_stylesheet() is deprecated. ' - 'Please use app.add_css_file() instead.', - RemovedInSphinx40Warning, stacklevel=2) - - attributes = {} # type: Dict[str, Any] - if alternate: - attributes['rel'] = 'alternate stylesheet' - else: - attributes['rel'] = 'stylesheet' - - if title: - attributes['title'] = title - - self.add_css_file(filename, **attributes) - def add_latex_package(self, packagename: str, options: str = None, after_hyperref: bool = False) -> None: r"""Register a package to include in the LaTeX source code. @@ -1102,7 +1076,7 @@ class Sphinx: """ self.registry.add_latex_package(packagename, options, after_hyperref) - def add_lexer(self, alias: str, lexer: Union[Lexer, "Type[Lexer]"]) -> None: + def add_lexer(self, alias: str, lexer: Type[Lexer]) -> None: """Register a new lexer for source code. Use *lexer* to highlight code blocks with the given language *alias*. @@ -1113,13 +1087,7 @@ class Sphinx: still supported until Sphinx-3.x. """ logger.debug('[app] adding lexer: %r', (alias, lexer)) - if isinstance(lexer, Lexer): - warnings.warn('app.add_lexer() API changed; ' - 'Please give lexer class instead of instance', - RemovedInSphinx40Warning, stacklevel=2) - lexers[alias] = lexer - else: - lexer_classes[alias] = lexer + lexer_classes[alias] = lexer def add_autodocumenter(self, cls: Any, override: bool = False) -> None: """Register a new documenter class for the autodoc extension. @@ -1133,7 +1101,7 @@ class Sphinx: If *override* is True, the given *cls* is forcedly installed even if a documenter having the same name is already installed. - .. todo:: Add real docs for Documenter and subclassing + See :ref:`autodoc_ext_tutorial`. .. versionadded:: 0.6 .. versionchanged:: 2.2 @@ -1144,7 +1112,7 @@ class Sphinx: self.registry.add_documenter(cls.objtype, cls) self.add_directive('auto' + cls.objtype, AutodocDirective, override=override) - def add_autodoc_attrgetter(self, typ: "Type", getter: Callable[[Any, str, Any], Any] + def add_autodoc_attrgetter(self, typ: Type, getter: Callable[[Any, str, Any], Any] ) -> None: """Register a new ``getattr``-like function for the autodoc extension. @@ -1188,7 +1156,7 @@ class Sphinx: """ self.registry.add_source_suffix(suffix, filetype, override=override) - def add_source_parser(self, parser: "Type[Parser]", override: bool = False) -> None: + def add_source_parser(self, parser: Type[Parser], override: bool = False) -> None: """Register a parser class. If *override* is True, the given *parser* is forcedly installed even if @@ -1203,7 +1171,7 @@ class Sphinx: """ self.registry.add_source_parser(parser, override=override) - def add_env_collector(self, collector: "Type[EnvironmentCollector]") -> None: + def add_env_collector(self, collector: Type[EnvironmentCollector]) -> None: """Register an environment collector class. Refer to :ref:`collector-api`. |