diff --git a/.ruff.toml b/.ruff.toml index 6150ff16c..5185c7150 100644 --- a/.ruff.toml +++ b/.ruff.toml @@ -393,7 +393,6 @@ required-imports = [ preview = true quote-style = "single" exclude = [ - "sphinx/application.py", "sphinx/builders/latex/constants.py", "sphinx/config.py", "sphinx/domains/__init__.py", diff --git a/sphinx/application.py b/sphinx/application.py index 9364ece1f..a0414aa64 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -145,14 +145,25 @@ class Sphinx: outdir = _StrPathProperty() doctreedir = _StrPathProperty() - def __init__(self, srcdir: str | os.PathLike[str], confdir: str | os.PathLike[str] | None, - outdir: str | os.PathLike[str], doctreedir: str | os.PathLike[str], - buildername: str, confoverrides: dict | None = None, - status: IO[str] | None = sys.stdout, warning: IO[str] | None = sys.stderr, - freshenv: bool = False, warningiserror: bool = False, - tags: Sequence[str] = (), - verbosity: int = 0, parallel: int = 0, keep_going: bool = False, - pdb: bool = False, exception_on_warning: bool = False) -> None: + def __init__( + self, + srcdir: str | os.PathLike[str], + confdir: str | os.PathLike[str] | None, + outdir: str | os.PathLike[str], + doctreedir: str | os.PathLike[str], + buildername: str, + confoverrides: dict | None = None, + status: IO[str] | None = sys.stdout, + warning: IO[str] | None = sys.stderr, + freshenv: bool = False, + warningiserror: bool = False, + tags: Sequence[str] = (), + verbosity: int = 0, + parallel: int = 0, + keep_going: bool = False, + pdb: bool = False, + exception_on_warning: bool = False, + ) -> None: """Initialize the Sphinx application. :param srcdir: The path to the source directory. @@ -187,16 +198,19 @@ class Sphinx: self.doctreedir = _StrPath(doctreedir).resolve() if not self.srcdir.is_dir(): - raise ApplicationError(__('Cannot find source directory (%s)') % - self.srcdir) + raise ApplicationError( + __('Cannot find source directory (%s)') % self.srcdir + ) if self.outdir.exists() and not self.outdir.is_dir(): - raise ApplicationError(__('Output directory (%s) is not a directory') % - self.outdir) + raise ApplicationError( + __('Output directory (%s) is not a directory') % self.outdir + ) if self.srcdir == self.outdir: - raise ApplicationError(__('Source directory and destination ' - 'directory cannot be identical')) + raise ApplicationError( + __('Source directory and destination directory cannot be identical') + ) self.parallel = parallel @@ -245,10 +259,17 @@ class Sphinx: self._init_i18n() # check the Sphinx version if requested - if self.config.needs_sphinx and self.config.needs_sphinx > sphinx.__display_version__: + if ( + self.config.needs_sphinx + and self.config.needs_sphinx > sphinx.__display_version__ + ): raise VersionRequirementError( - __('This project needs at least Sphinx v%s and therefore cannot ' - 'be built with this version.') % self.config.needs_sphinx) + __( + 'This project needs at least Sphinx v%s and therefore cannot ' + 'be built with this version.' + ) + % self.config.needs_sphinx + ) # load all built-in extension modules, first-party extension modules, # and first-party themes @@ -268,15 +289,17 @@ class Sphinx: # the config file itself can be an extension if self.config.setup: - prefix = __('while setting up extension %s:') % "conf.py" + prefix = __('while setting up extension %s:') % 'conf.py' with prefixed_warnings(prefix): if callable(self.config.setup): self.config.setup(self) else: raise ConfigError( - __("'setup' as currently defined in conf.py isn't a Python callable. " - "Please modify its definition to make it a callable function. " - "This is needed for conf.py to behave as a Sphinx extension."), + __( + "'setup' as currently defined in conf.py isn't a Python callable. " + 'Please modify its definition to make it a callable function. ' + 'This is needed for conf.py to behave as a Sphinx extension.' + ), ) # Report any warnings for overrides. @@ -309,22 +332,30 @@ class Sphinx: """Load translated strings from the configured localedirs if enabled in the configuration. """ - logger.info(bold(__('loading translations [%s]... ')), self.config.language, - nonl=True) + logger.info( + bold(__('loading translations [%s]... ')), self.config.language, nonl=True + ) # compile mo files if sphinx.po file in user locale directories are updated - repo = CatalogRepository(self.srcdir, self.config.locale_dirs, - self.config.language, self.config.source_encoding) + repo = CatalogRepository( + self.srcdir, + self.config.locale_dirs, + self.config.language, + self.config.source_encoding, + ) for catalog in repo.catalogs: if catalog.domain == 'sphinx' and catalog.is_outdated(): - catalog.write_mo(self.config.language, - self.config.gettext_allow_fuzzy_translations) + catalog.write_mo( + self.config.language, self.config.gettext_allow_fuzzy_translations + ) locale_dirs: list[_StrPath | None] = list(repo.locale_dirs) locale_dirs += [None] locale_dirs += [_StrPath(package_dir, 'locale')] - self.translator, has_translation = locale.init(locale_dirs, self.config.language) + self.translator, has_translation = locale.init( + locale_dirs, self.config.language + ) if has_translation or self.config.language == 'en': logger.info(__('done')) else: @@ -374,7 +405,9 @@ class Sphinx: # ---- main "build" method ------------------------------------------------- - def build(self, force_all: bool = False, filenames: list[str] | None = None) -> None: + def build( + self, force_all: bool = False, filenames: list[str] | None = None + ) -> None: self.phase = BuildPhase.READING try: if force_all: @@ -401,8 +434,10 @@ class Sphinx: elif self._warncount == 1: if self._fail_on_warnings: self.statuscode = 1 - msg = __('build finished with problems, 1 warning ' - '(with warnings treated as errors).') + msg = __( + 'build finished with problems, 1 warning ' + '(with warnings treated as errors).' + ) elif self.statuscode != 0: msg = __('build finished with problems, 1 warning.') else: @@ -411,8 +446,10 @@ class Sphinx: else: if self._fail_on_warnings: self.statuscode = 1 - msg = __('build finished with problems, %s warnings ' - '(with warnings treated as errors).') + msg = __( + 'build finished with problems, %s warnings ' + '(with warnings treated as errors).' + ) elif self.statuscode != 0: msg = __('build finished with problems, %s warnings.') else: @@ -421,10 +458,13 @@ class Sphinx: if self.statuscode == 0 and self.builder.epilog: logger.info('') - logger.info(self.builder.epilog, { - 'outdir': relpath(self.outdir), - 'project': self.config.project, - }) + logger.info( + self.builder.epilog, + { + 'outdir': relpath(self.outdir), + 'project': self.config.project, + }, + ) self.builder.cleanup() @@ -465,235 +505,214 @@ class Sphinx: # ---- Core events ------------------------------------------------------- @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['config-inited'], callback: Callable[[Sphinx, Config], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['builder-inited'], callback: Callable[[Sphinx], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['env-get-outdated'], callback: Callable[ [Sphinx, BuildEnvironment, Set[str], Set[str], Set[str]], Sequence[str] ], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['env-before-read-docs'], callback: Callable[[Sphinx, BuildEnvironment, list[str]], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['env-purge-doc'], callback: Callable[[Sphinx, BuildEnvironment, str], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['source-read'], callback: Callable[[Sphinx, str, list[str]], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['include-read'], callback: Callable[[Sphinx, Path, str, list[str]], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['doctree-read'], callback: Callable[[Sphinx, nodes.document], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['env-merge-info'], callback: Callable[ [Sphinx, BuildEnvironment, Set[str], BuildEnvironment], None ], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['env-updated'], callback: Callable[[Sphinx, BuildEnvironment], str], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['env-get-updated'], callback: Callable[[Sphinx, BuildEnvironment], Iterable[str]], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['env-check-consistency'], callback: Callable[[Sphinx, BuildEnvironment], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['write-started'], callback: Callable[[Sphinx, Builder], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['doctree-resolved'], callback: Callable[[Sphinx, nodes.document, str], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['missing-reference'], callback: Callable[ [Sphinx, BuildEnvironment, addnodes.pending_xref, nodes.TextElement], nodes.reference | None, ], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['warn-missing-reference'], callback: Callable[[Sphinx, Domain, addnodes.pending_xref], bool | None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['build-finished'], callback: Callable[[Sphinx, Exception | None], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... # ---- Events from builtin builders -------------------------------------- @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['html-collect-pages'], callback: Callable[[Sphinx], Iterable[tuple[str, dict[str, Any], str]]], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['html-page-context'], callback: Callable[ [Sphinx, str, str, dict[str, Any], nodes.document], str | None ], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['linkcheck-process-uri'], callback: Callable[[Sphinx, str], str | None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... # ---- Events from builtin extensions-- ---------------------------------- @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['object-description-transform'], callback: Callable[[Sphinx, str, str, addnodes.desc_content], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... # ---- Events from first-party extensions -------------------------------- @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['autodoc-process-docstring'], callback: _AutodocProcessDocstringListener, - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['autodoc-before-process-signature'], callback: Callable[[Sphinx, Any, bool], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['autodoc-process-signature'], callback: Callable[ [ Sphinx, - Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], + Literal[ + 'module', 'class', 'exception', 'function', 'method', 'attribute' + ], str, Any, dict[str, bool], @@ -702,27 +721,27 @@ class Sphinx: ], tuple[str | None, str | None] | None, ], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['autodoc-process-bases'], callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['autodoc-skip-member'], callback: Callable[ [ Sphinx, - Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], + Literal[ + 'module', 'class', 'exception', 'function', 'method', 'attribute' + ], str, Any, bool, @@ -730,21 +749,19 @@ class Sphinx: ], bool, ], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['todo-defined'], callback: Callable[[Sphinx, todo_node], None], priority: int = 500, - ) -> int: - ... + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['viewcode-find-source'], callback: Callable[ @@ -752,28 +769,25 @@ class Sphinx: tuple[str, dict[str, tuple[Literal['class', 'def', 'other'], int, int]]], ], priority: int = 500, - ) -> int: - ... + ) -> int: ... @overload - def connect( + def connect( # NoQA: E704 self, event: Literal['viewcode-follow-imported'], callback: Callable[[Sphinx, str, str], str | None], priority: int = 500, - ) -> int: - ... + ) -> int: ... # ---- Catch-all --------------------------------------------------------- @overload - def connect( + def connect( # NoQA: E704 self, event: str, callback: Callable[..., Any], - priority: int = 500 - ) -> int: - ... + priority: int = 500, + ) -> int: ... # event interface def connect(self, event: str, callback: Callable, priority: int = 500) -> int: @@ -793,8 +807,13 @@ class Sphinx: Support *priority* """ listener_id = self.events.connect(event, callback, priority) - logger.debug('[app] connecting event %r (%d): %r [id=%s]', - event, priority, callback, listener_id) + logger.debug( + '[app] connecting event %r (%d): %r [id=%s]', + event, + priority, + callback, + listener_id, + ) return listener_id def disconnect(self, listener_id: int) -> None: @@ -805,8 +824,12 @@ class Sphinx: logger.debug('[app] disconnecting event: [id=%s]', listener_id) self.events.disconnect(listener_id) - def emit(self, event: str, *args: Any, - allowed_exceptions: tuple[type[Exception], ...] = ()) -> list: + def emit( + self, + event: str, + *args: Any, + 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 @@ -822,8 +845,12 @@ 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: + def emit_firstresult( + self, + event: str, + *args: 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``. @@ -837,8 +864,9 @@ class Sphinx: Added *allowed_exceptions* to specify path-through exceptions """ - return self.events.emit_firstresult(event, *args, - allowed_exceptions=allowed_exceptions) + return self.events.emit_firstresult( + event, *args, allowed_exceptions=allowed_exceptions + ) # registering addon parts @@ -855,7 +883,10 @@ class Sphinx: self.registry.add_builder(builder, override=override) def add_config_value( - self, name: str, default: Any, rebuild: _ConfigRebuild, + self, + name: str, + default: Any, + rebuild: _ConfigRebuild, types: type | Collection[type] | ENUM = (), description: str = '', ) -> None: @@ -908,8 +939,12 @@ class Sphinx: logger.debug('[app] adding event: %r', name) self.events.add(name) - def set_translator(self, name: str, translator_class: type[nodes.NodeVisitor], - override: bool = False) -> None: + def set_translator( + self, + name: str, + translator_class: type[nodes.NodeVisitor], + override: bool = False, + ) -> None: """Register or override a Docutils translator class. This is used to register a custom output translator or to replace a @@ -927,8 +962,12 @@ class Sphinx: """ self.registry.add_translator(name, translator_class, override=override) - def add_node(self, node: type[Element], override: bool = False, - **kwargs: tuple[Callable, Callable | None]) -> None: + def add_node( + self, + node: type[Element], + override: bool = False, + **kwargs: tuple[Callable, Callable | None], + ) -> None: """Register a Docutils node class. This is necessary for Docutils internals. It may also be used in the @@ -965,15 +1004,26 @@ class Sphinx: """ logger.debug('[app] adding node: %r', (node, kwargs)) if not override and docutils.is_node_registered(node): - logger.warning(__('node class %r is already registered, ' - 'its visitors will be overridden'), - node.__name__, type='app', subtype='add_node') + logger.warning( + __( + 'node class %r is already registered, ' + 'its visitors will be overridden' + ), + node.__name__, + type='app', + subtype='add_node', + ) docutils.register_node(node) self.registry.add_translation_handlers(node, **kwargs) - def add_enumerable_node(self, node: type[Element], figtype: str, - title_getter: TitleGetter | None = None, override: bool = False, - **kwargs: tuple[Callable, Callable]) -> None: + def add_enumerable_node( + self, + node: type[Element], + figtype: str, + title_getter: TitleGetter | None = None, + override: bool = False, + **kwargs: tuple[Callable, Callable], + ) -> None: """Register a Docutils node class as a numfig target. Sphinx numbers the node automatically. And then the users can refer it @@ -997,10 +1047,14 @@ class Sphinx: .. versionadded:: 1.4 """ - self.registry.add_enumerable_node(node, figtype, title_getter, override=override) + 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 the directive @@ -1044,8 +1098,12 @@ class Sphinx: """ logger.debug('[app] adding directive: %r', (name, cls)) if not override and docutils.is_directive_registered(name): - logger.warning(__('directive %r is already registered, it will be overridden'), - name, type='app', subtype='add_directive') + logger.warning( + __('directive %r is already registered, it will be overridden'), + name, + type='app', + subtype='add_directive', + ) docutils.register_directive(name, cls) @@ -1066,13 +1124,16 @@ class Sphinx: """ logger.debug('[app] adding role: %r', (name, role)) if not override and docutils.is_role_registered(name): - logger.warning(__('role %r is already registered, it will be overridden'), - name, type='app', subtype='add_role') + logger.warning( + __('role %r is already registered, it will be overridden'), + name, + type='app', + subtype='add_role', + ) docutils.register_role(name, role) def add_generic_role( self, name: str, nodeclass: type[Node], override: bool = False - ) -> None: """Register a generic Docutils role. @@ -1091,8 +1152,12 @@ class Sphinx: # ``register_canonical_role``. logger.debug('[app] adding generic role: %r', (name, nodeclass)) if not override and docutils.is_role_registered(name): - logger.warning(__('role %r is already registered, it will be overridden'), - name, type='app', subtype='add_generic_role') + logger.warning( + __('role %r is already registered, it will be overridden'), + name, + type='app', + subtype='add_generic_role', + ) role = roles.GenericRole(name, nodeclass) docutils.register_role(name, role) @@ -1110,8 +1175,9 @@ 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: + def add_directive_to_domain( + self, domain: str, name: str, 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 @@ -1130,8 +1196,13 @@ class Sphinx: """ self.registry.add_directive_to_domain(domain, name, cls, override=override) - def add_role_to_domain(self, domain: str, name: str, role: RoleFunction | XRefRole, - override: bool = False) -> None: + def add_role_to_domain( + self, + domain: str, + name: str, + role: RoleFunction | XRefRole, + override: bool = False, + ) -> None: """Register a Docutils role in a domain. Like :meth:`add_role`, but the role is added to the domain named @@ -1150,8 +1221,9 @@ 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, - ) -> None: + def add_index_to_domain( + self, domain: str, index: type[Index], _override: bool = False + ) -> None: """Register a custom index for a domain. Add a custom *index* class to the domain named *domain*. @@ -1168,12 +1240,17 @@ 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 = None, - ref_nodeclass: type[nodes.TextElement] | None = None, - objname: str = '', doc_field_types: Sequence = (), - override: bool = False, - ) -> None: + def add_object_type( + self, + directivename: str, + rolename: str, + indextemplate: str = '', + parse_node: Callable | None = None, + ref_nodeclass: type[nodes.TextElement] | None = None, + objname: str = '', + doc_field_types: Sequence = (), + override: bool = False, + ) -> None: """Register a new object type. This method is a very convenient way to add a new :term:`object` type @@ -1233,13 +1310,24 @@ class Sphinx: .. versionchanged:: 1.8 Add *override* keyword. """ - self.registry.add_object_type(directivename, rolename, indextemplate, parse_node, - ref_nodeclass, objname, doc_field_types, - override=override) + self.registry.add_object_type( + directivename, + rolename, + indextemplate, + parse_node, + ref_nodeclass, + objname, + doc_field_types, + override=override, + ) def add_crossref_type( - self, directivename: str, rolename: str, indextemplate: str = '', - ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', + self, + directivename: str, + rolename: str, + indextemplate: str = '', + ref_nodeclass: type[nodes.TextElement] | None = None, + objname: str = '', override: bool = False, ) -> None: """Register a new crossref object type. @@ -1276,9 +1364,14 @@ class Sphinx: .. versionchanged:: 1.8 Add *override* keyword. """ - self.registry.add_crossref_type(directivename, rolename, - indextemplate, ref_nodeclass, objname, - override=override) + self.registry.add_crossref_type( + directivename, + rolename, + indextemplate, + ref_nodeclass, + objname, + override=override, + ) def add_transform(self, transform: type[Transform]) -> None: """Register a Docutils transform to be applied after parsing. @@ -1326,8 +1419,13 @@ class Sphinx: """ self.registry.add_post_transform(transform) - def add_js_file(self, filename: str | None, priority: int = 500, - loading_method: str | None = None, **kwargs: Any) -> None: + def add_js_file( + self, + filename: str | None, + priority: int = 500, + loading_method: str | None = None, + **kwargs: Any, + ) -> None: """Register a JavaScript file to include in the HTML output. :param filename: The name of a JavaScript file that the default HTML @@ -1393,7 +1491,7 @@ class Sphinx: self.registry.add_js_file(filename, priority=priority, **kwargs) with contextlib.suppress(AttributeError): self.builder.add_js_file( # type: ignore[attr-defined] - filename, priority=priority, **kwargs, + filename, priority=priority, **kwargs ) def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None: @@ -1457,11 +1555,12 @@ class Sphinx: self.registry.add_css_files(filename, priority=priority, **kwargs) with contextlib.suppress(AttributeError): self.builder.add_css_file( # type: ignore[attr-defined] - filename, priority=priority, **kwargs, + filename, priority=priority, **kwargs ) - def add_latex_package(self, packagename: str, options: str | None = None, - after_hyperref: bool = False) -> None: + def add_latex_package( + self, packagename: str, options: str | None = None, after_hyperref: bool = False + ) -> None: r"""Register a package to include in the LaTeX source code. Add *packagename* to the list of packages that LaTeX source code will @@ -1517,11 +1616,13 @@ class Sphinx: """ logger.debug('[app] adding autodocumenter: %r', cls) from sphinx.ext.autodoc.directive import AutodocDirective + 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], - ) -> None: + def add_autodoc_attrgetter( + self, typ: type, getter: Callable[[Any, str, Any], Any] + ) -> None: """Register a new ``getattr``-like function for the autodoc extension. Add *getter*, which must be a function with an interface compatible to @@ -1548,9 +1649,12 @@ class Sphinx: """ logger.debug('[app] adding search language: %r', cls) from sphinx.search import languages + languages[cls.lang] = cls - def add_source_suffix(self, suffix: str, filetype: str, override: bool = False) -> None: + def add_source_suffix( + self, suffix: str, filetype: str, override: bool = False + ) -> None: """Register a suffix of source files. Same as :confval:`source_suffix`. The users can override this @@ -1620,7 +1724,9 @@ class Sphinx: """ self.registry.add_html_math_renderer(name, inline_renderers, block_renderers) - def add_message_catalog(self, catalog: str, locale_dir: str | os.PathLike[str]) -> None: + def add_message_catalog( + self, catalog: str, locale_dir: str | os.PathLike[str] + ) -> None: """Register a message catalog. :param catalog: The name of the catalog @@ -1641,18 +1747,22 @@ class Sphinx: """ if typ == 'read': attrname = 'parallel_read_safe' - message_not_declared = __("the %s extension does not declare if it " - "is safe for parallel reading, assuming " - "it isn't - please ask the extension author " - "to check and make it explicit") - message_not_safe = __("the %s extension is not safe for parallel reading") + message_not_declared = __( + 'the %s extension does not declare if it ' + 'is safe for parallel reading, assuming ' + "it isn't - please ask the extension author " + 'to check and make it explicit' + ) + message_not_safe = __('the %s extension is not safe for parallel reading') elif typ == 'write': attrname = 'parallel_write_safe' - message_not_declared = __("the %s extension does not declare if it " - "is safe for parallel writing, assuming " - "it isn't - please ask the extension author " - "to check and make it explicit") - message_not_safe = __("the %s extension is not safe for parallel writing") + message_not_declared = __( + 'the %s extension does not declare if it ' + 'is safe for parallel writing, assuming ' + "it isn't - please ask the extension author " + 'to check and make it explicit' + ) + message_not_safe = __('the %s extension is not safe for parallel writing') else: raise ValueError('parallel type %s is not supported' % typ)