py2docfx 0.1.11.dev1827111__py3-none-any.whl → 0.1.11.dev1859874__py3-none-any.whl

py2docfx/venv/template/Lib/site-packages/sphinx/application.py

@@ -1,1344 +0,0 @@
-"""Sphinx application class and extensibility interface.
-
-Gracefully adapted from the TextPress system by Armin.
-"""
-
-from __future__ import annotations
-
-import os
-import pickle
-import sys
-from collections import deque
-from io import StringIO
-from os import path
-from typing import IO, TYPE_CHECKING, Any, Callable
-
-from docutils import nodes
-from docutils.nodes import Element, TextElement
-from docutils.parsers import Parser
-from docutils.parsers.rst import Directive, roles
-from docutils.transforms import Transform
-from pygments.lexer import Lexer
-
-import sphinx
-from sphinx import locale, package_dir
-from sphinx.config import Config
-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
-from sphinx.locale import __
-from sphinx.project import Project
-from sphinx.registry import SphinxComponentRegistry
-from sphinx.roles import XRefRole
-from sphinx.theming import Theme
-from sphinx.util import docutils, logging
-from sphinx.util.build_phase import BuildPhase
-from sphinx.util.console import bold  # type: ignore
-from sphinx.util.display import progress_message
-from sphinx.util.i18n import CatalogRepository
-from sphinx.util.logging import prefixed_warnings
-from sphinx.util.osutil import abspath, ensuredir, relpath
-from sphinx.util.tags import Tags
-from sphinx.util.typing import RoleFunction, TitleGetter
-
-if TYPE_CHECKING:
-    from docutils.nodes import Node  # noqa: F401
-
-    from sphinx.builders import Builder
-
-
-builtin_extensions = (
-    'sphinx.addnodes',
-    'sphinx.builders.changes',
-    'sphinx.builders.epub3',
-    'sphinx.builders.dirhtml',
-    'sphinx.builders.dummy',
-    'sphinx.builders.gettext',
-    'sphinx.builders.html',
-    'sphinx.builders.latex',
-    'sphinx.builders.linkcheck',
-    'sphinx.builders.manpage',
-    'sphinx.builders.singlehtml',
-    'sphinx.builders.texinfo',
-    'sphinx.builders.text',
-    'sphinx.builders.xml',
-    'sphinx.config',
-    'sphinx.domains.c',
-    'sphinx.domains.changeset',
-    'sphinx.domains.citation',
-    'sphinx.domains.cpp',
-    'sphinx.domains.index',
-    'sphinx.domains.javascript',
-    'sphinx.domains.math',
-    'sphinx.domains.python',
-    'sphinx.domains.rst',
-    'sphinx.domains.std',
-    'sphinx.directives',
-    'sphinx.directives.code',
-    'sphinx.directives.other',
-    'sphinx.directives.patches',
-    'sphinx.extension',
-    'sphinx.parsers',
-    'sphinx.registry',
-    'sphinx.roles',
-    'sphinx.transforms',
-    'sphinx.transforms.compact_bullet_list',
-    'sphinx.transforms.i18n',
-    'sphinx.transforms.references',
-    'sphinx.transforms.post_transforms',
-    'sphinx.transforms.post_transforms.code',
-    'sphinx.transforms.post_transforms.images',
-    'sphinx.versioning',
-    # collectors should be loaded by specific order
-    'sphinx.environment.collectors.dependencies',
-    'sphinx.environment.collectors.asset',
-    'sphinx.environment.collectors.metadata',
-    'sphinx.environment.collectors.title',
-    'sphinx.environment.collectors.toctree',
-    # 1st party extensions
-    'sphinxcontrib.applehelp',
-    'sphinxcontrib.devhelp',
-    'sphinxcontrib.htmlhelp',
-    'sphinxcontrib.serializinghtml',
-    'sphinxcontrib.qthelp',
-    # Strictly, alabaster theme is not a builtin extension,
-    # but it is loaded automatically to use it as default theme.
-    'alabaster',
-)
-
-ENV_PICKLE_FILENAME = 'environment.pickle'
-
-logger = logging.getLogger(__name__)
-
-
-class Sphinx:
-    """The main application class and extensibility interface.
-
-    :ivar srcdir: Directory containing source.
-    :ivar confdir: Directory containing ``conf.py``.
-    :ivar doctreedir: Directory for storing pickled doctrees.
-    :ivar outdir: Directory for storing build documents.
-    """
-
-    warningiserror: bool
-    _warncount: int
-
-    def __init__(self, srcdir: str, confdir: str | None, outdir: str, doctreedir: str,
-                 buildername: str, confoverrides: dict | None = None,
-                 status: IO | None = sys.stdout, warning: IO | None = sys.stderr,
-                 freshenv: bool = False, warningiserror: bool = False,
-                 tags: list[str] | None = None,
-                 verbosity: int = 0, parallel: int = 0, keep_going: bool = False,
-                 pdb: bool = False) -> None:
-        self.phase = BuildPhase.INITIALIZATION
-        self.verbosity = verbosity
-        self.extensions: dict[str, Extension] = {}
-        self.registry = SphinxComponentRegistry()
-
-        # validate provided directories
-        self.srcdir = abspath(srcdir)
-        self.outdir = abspath(outdir)
-        self.doctreedir = abspath(doctreedir)
-
-        if not path.isdir(self.srcdir):
-            raise ApplicationError(__('Cannot find source directory (%s)') %
-                                   self.srcdir)
-
-        if path.exists(self.outdir) and not path.isdir(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'))
-
-        self.parallel = parallel
-
-        if status is None:
-            self._status: IO = StringIO()
-            self.quiet: bool = True
-        else:
-            self._status = status
-            self.quiet = False
-
-        if warning is None:
-            self._warning: IO = StringIO()
-        else:
-            self._warning = warning
-        self._warncount = 0
-        self.keep_going = warningiserror and keep_going
-        if self.keep_going:
-            self.warningiserror = False
-        else:
-            self.warningiserror = warningiserror
-        self.pdb = pdb
-        logging.setup(self, self._status, self._warning)
-
-        self.events = EventManager(self)
-
-        # keep last few messages for traceback
-        # This will be filled by sphinx.util.logging.LastMessagesWriter
-        self.messagelog: deque = deque(maxlen=10)
-
-        # say hello to the world
-        logger.info(bold(__('Running Sphinx v%s') % sphinx.__display_version__))
-
-        # status code for command-line application
-        self.statuscode = 0
-
-        # read config
-        self.tags = Tags(tags)
-        if confdir is None:
-            # set confdir to srcdir if -C given (!= no confdir); a few pieces
-            # of code expect a confdir to be set
-            self.confdir = self.srcdir
-            self.config = Config({}, confoverrides or {})
-        else:
-            self.confdir = abspath(confdir)
-            self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
-
-        # initialize some limited config variables before initialize i18n and loading
-        # extensions
-        self.config.pre_init_values()
-
-        # set up translation infrastructure
-        self._init_i18n()
-
-        # check the Sphinx version if requested
-        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)
-
-        # load all built-in extension modules
-        for extension in builtin_extensions:
-            self.setup_extension(extension)
-
-        # load all user-given extension modules
-        for extension in self.config.extensions:
-            self.setup_extension(extension)
-
-        # preload builder module (before init config values)
-        self.preload_builder(buildername)
-
-        if not path.isdir(outdir):
-            with progress_message(__('making output directory')):
-                ensuredir(outdir)
-
-        # the config file itself can be an extension
-        if self.config.setup:
-            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.")
-                    )
-
-        # now that we know all config values, collect them from conf.py
-        self.config.init_values()
-        self.events.emit('config-inited', self.config)
-
-        # create the project
-        self.project = Project(self.srcdir, self.config.source_suffix)
-
-        # set up the build environment
-        self.env = self._init_env(freshenv)
-
-        # create the builder
-        self.builder = self.create_builder(buildername)
-
-        # build environment post-initialisation, after creating the builder
-        self._post_init_env()
-
-        # set up the builder
-        self._init_builder()
-
-    def _init_i18n(self) -> None:
-        """Load translated strings from the configured localedirs if enabled in
-        the configuration.
-        """
-        if self.config.language == 'en':
-            self.translator, has_translation = locale.init([], None)
-        else:
-            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)
-            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)
-
-            locale_dirs: list[str | None] = list(repo.locale_dirs)
-            locale_dirs += [None]
-            locale_dirs += [path.join(package_dir, 'locale')]
-
-            self.translator, has_translation = locale.init(locale_dirs, self.config.language)
-            if has_translation:
-                logger.info(__('done'))
-            else:
-                logger.info(__('not available for built-in messages'))
-
-    def _init_env(self, freshenv: bool) -> BuildEnvironment:
-        filename = path.join(self.doctreedir, ENV_PICKLE_FILENAME)
-        if freshenv or not os.path.exists(filename):
-            return self._create_fresh_env()
-        else:
-            return self._load_existing_env(filename)
-
-    def _create_fresh_env(self) -> BuildEnvironment:
-        env = BuildEnvironment(self)
-        self._fresh_env_used = True
-        return env
-
-    def _load_existing_env(self, filename: str) -> BuildEnvironment:
-        try:
-            with progress_message(__('loading pickled environment')):
-                with open(filename, 'rb') as f:
-                    env = pickle.load(f)
-                    env.setup(self)
-                    self._fresh_env_used = False
-        except Exception as err:
-            logger.info(__('failed: %s'), err)
-            env = self._create_fresh_env()
-        return env
-
-    def _post_init_env(self) -> None:
-        if self._fresh_env_used:
-            self.env.find_files(self.config, self.builder)
-        del self._fresh_env_used
-
-    def preload_builder(self, name: str) -> None:
-        self.registry.preload_builder(self, name)
-
-    def create_builder(self, name: str) -> Builder:
-        if name is None:
-            logger.info(__('No builder selected, using default: html'))
-            name = 'html'
-
-        return self.registry.create_builder(self, name, self.env)
-
-    def _init_builder(self) -> None:
-        if not hasattr(self.builder, "env"):
-            self.builder.set_environment(self.env)
-        self.builder.init()
-        self.events.emit('builder-inited')
-
-    # ---- main "build" method -------------------------------------------------
-
-    def build(self, force_all: bool = False, filenames: list[str] | None = None) -> None:
-        self.phase = BuildPhase.READING
-        try:
-            if force_all:
-                self.builder.build_all()
-            elif filenames:
-                self.builder.build_specific(filenames)
-            else:
-                self.builder.build_update()
-
-            self.events.emit('build-finished', None)
-        except Exception as err:
-            # delete the saved env to force a fresh build next time
-            envfile = path.join(self.doctreedir, ENV_PICKLE_FILENAME)
-            if path.isfile(envfile):
-                os.unlink(envfile)
-            self.events.emit('build-finished', err)
-            raise
-
-        if self._warncount and self.keep_going:
-            self.statuscode = 1
-
-        status = (__('succeeded') if self.statuscode == 0
-                  else __('finished with problems'))
-        if self._warncount:
-            if self.warningiserror:
-                if self._warncount == 1:
-                    msg = __('build %s, %s warning (with warnings treated as errors).')
-                else:
-                    msg = __('build %s, %s warnings (with warnings treated as errors).')
-            else:
-                if self._warncount == 1:
-                    msg = __('build %s, %s warning.')
-                else:
-                    msg = __('build %s, %s warnings.')
-
-            logger.info(bold(msg % (status, self._warncount)))
-        else:
-            logger.info(bold(__('build %s.') % status))
-
-        if self.statuscode == 0 and self.builder.epilog:
-            logger.info('')
-            logger.info(self.builder.epilog % {
-                'outdir': relpath(self.outdir),
-                'project': self.config.project
-            })
-
-        self.builder.cleanup()
-
-    # ---- general extensibility interface -------------------------------------
-
-    def setup_extension(self, extname: str) -> None:
-        """Import and setup a Sphinx extension module.
-
-        Load the extension given by the module *name*.  Use this if your
-        extension needs the features provided by another extension.  No-op if
-        called twice.
-        """
-        logger.debug('[app] setting up extension: %r', extname)
-        self.registry.load_extension(self, extname)
-
-    def require_sphinx(self, version: str) -> None:
-        """Check the Sphinx version if requested.
-
-        Compare *version* with the version of the running Sphinx, and abort the
-        build when it is too old.
-
-        :param version: The required version in the form of ``major.minor``.
-
-        .. versionadded:: 1.0
-        """
-        if version > sphinx.__display_version__[:3]:
-            raise VersionRequirementError(version)
-
-    # event interface
-    def connect(self, event: str, callback: Callable, priority: int = 500) -> int:
-        """Register *callback* to be called when *event* is emitted.
-
-        For details on available core events and the arguments of callback
-        functions, please see :ref:`events`.
-
-        :param event: The name of target event
-        :param callback: Callback function for the event
-        :param priority: The priority of the callback.  The callbacks will be invoked
-                         in order of *priority* (ascending).
-        :return: A listener ID.  It can be used for :meth:`disconnect`.
-
-        .. versionchanged:: 3.0
-
-           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)
-        return listener_id
-
-    def disconnect(self, listener_id: int) -> None:
-        """Unregister callback by *listener_id*.
-
-        :param listener_id: A listener_id that :meth:`connect` returns
-        """
-        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:
-        """Emit *event* and pass *arguments* to the callback functions.
-
-        Return the return values of all callbacks as a list.  Do not emit core
-        Sphinx events in extensions!
-
-        :param event: The name of event that will be emitted
-        :param args: The arguments for the event
-        :param allowed_exceptions: The list of exceptions that are allowed in the callbacks
-
-        .. versionchanged:: 3.1
-
-           Added *allowed_exceptions* to specify path-through exceptions
-        """
-        return self.events.emit(event, *args, allowed_exceptions=allowed_exceptions)
-
-    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``.
-
-        :param event: The name of event that will be emitted
-        :param args: The arguments for the event
-        :param allowed_exceptions: The list of exceptions that are allowed in the callbacks
-
-        .. versionadded:: 0.5
-        .. versionchanged:: 3.1
-
-           Added *allowed_exceptions* to specify path-through exceptions
-        """
-        return self.events.emit_firstresult(event, *args,
-                                            allowed_exceptions=allowed_exceptions)
-
-    # registering addon parts
-
-    def add_builder(self, builder: type[Builder], override: bool = False) -> None:
-        """Register a new builder.
-
-        :param builder: A builder class
-        :param override: If true, install the builder forcedly even if another builder
-                         is already installed as the same name
-
-        .. versionchanged:: 1.8
-           Add *override* keyword.
-        """
-        self.registry.add_builder(builder, override=override)
-
-    # TODO(stephenfin): Describe 'types' parameter
-    def add_config_value(self, name: str, default: Any, rebuild: bool | str,
-                         types: Any = ()) -> None:
-        """Register a configuration value.
-
-        This is necessary for Sphinx to recognize new values and set default
-        values accordingly.
-
-
-        :param name: The name of the configuration value.  It is recommended to be prefixed
-                     with the extension name (ex. ``html_logo``, ``epub_title``)
-        :param default: The default value of the configuration.
-        :param rebuild: The condition of rebuild.  It must be one of those values:
-
-                        * ``'env'`` if a change in the setting only takes effect when a
-                          document is parsed -- this means that the whole environment must be
-                          rebuilt.
-                        * ``'html'`` if a change in the setting needs a full rebuild of HTML
-                          documents.
-                        * ``''`` if a change in the setting will not need any special rebuild.
-        :param types: The type of configuration value.  A list of types can be specified.  For
-                      example, ``[str]`` is used to describe a configuration that takes string
-                      value.
-
-        .. versionchanged:: 0.4
-           If the *default* value is a callable, it will be called with the
-           config object as its argument in order to get the default value.
-           This can be used to implement config values whose default depends on
-           other values.
-
-        .. versionchanged:: 0.6
-           Changed *rebuild* from a simple boolean (equivalent to ``''`` or
-           ``'env'``) to a string.  However, booleans are still accepted and
-           converted internally.
-        """
-        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)
-
-    def add_event(self, name: str) -> None:
-        """Register an event called *name*.
-
-        This is needed to be able to emit it.
-
-        :param name: The name of the event
-        """
-        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:
-        """Register or override a Docutils translator class.
-
-        This is used to register a custom output translator or to replace a
-        builtin translator.  This allows extensions to use a custom translator
-        and define custom nodes for the translator (see :meth:`add_node`).
-
-        :param name: The name of the builder for the translator
-        :param translator_class: A translator class
-        :param override: If true, install the translator forcedly even if another translator
-                         is already installed as the same name
-
-        .. versionadded:: 1.3
-        .. versionchanged:: 1.8
-           Add *override* keyword.
-        """
-        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:
-        """Register a Docutils node class.
-
-        This is necessary for Docutils internals.  It may also be used in the
-        future to validate nodes in the parsed documents.
-
-        :param node: A node class
-        :param kwargs: Visitor functions for each builder (see below)
-        :param override: If true, install the node forcedly even if another node is already
-                         installed as the same name
-
-        Node visitor functions for the Sphinx HTML, LaTeX, text and manpage
-        writers can be given as keyword arguments: the keyword should be one or
-        more of ``'html'``, ``'latex'``, ``'text'``, ``'man'``, ``'texinfo'``
-        or any other supported translators, the value a 2-tuple of ``(visit,
-        depart)`` methods.  ``depart`` can be ``None`` if the ``visit``
-        function raises :exc:`docutils.nodes.SkipNode`.  Example:
-
-        .. code-block:: python
-
-           class math(docutils.nodes.Element): pass
-
-           def visit_math_html(self, node):
-               self.body.append(self.starttag(node, 'math'))
-           def depart_math_html(self, node):
-               self.body.append('</math>')
-
-           app.add_node(math, html=(visit_math_html, depart_math_html))
-
-        Obviously, translators for which you don't specify visitor methods will
-        choke on the node when encountered in a document to translate.
-
-        .. versionchanged:: 0.5
-           Added the support for keyword arguments giving visit functions.
-        """
-        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')
-        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:
-        """Register a Docutils node class as a numfig target.
-
-        Sphinx numbers the node automatically. And then the users can refer it
-        using :rst:role:`numref`.
-
-        :param node: A node class
-        :param figtype: The type of enumerable nodes.  Each figtype has individual numbering
-                        sequences.  As system figtypes, ``figure``, ``table`` and
-                        ``code-block`` are defined.  It is possible to add custom nodes to
-                        these default figtypes.  It is also possible to define new custom
-                        figtype if a new figtype is given.
-        :param title_getter: A getter function to obtain the title of node.  It takes an
-                             instance of the enumerable node, and it must return its title as
-                             string.  The title is used to the default title of references for
-                             :rst:role:`ref`.  By default, Sphinx searches
-                             ``docutils.nodes.caption`` or ``docutils.nodes.title`` from the
-                             node as a title.
-        :param kwargs: Visitor functions for each builder (same as :meth:`add_node`)
-        :param override: If true, install the node forcedly even if another node is already
-                         installed as the same name
-
-        .. versionadded:: 1.4
-        """
-        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:
-        """Register a Docutils directive.
-
-        :param name: The name of the directive
-        :param cls: A directive class
-        :param override: If false, do not install it if another directive
-                         is already installed as the same name
-                         If true, unconditionally install the directive.
-
-        For example, a custom directive named ``my-directive`` would be added
-        like this:
-
-        .. code-block:: python
-
-           from docutils.parsers.rst import Directive, directives
-
-           class MyDirective(Directive):
-               has_content = True
-               required_arguments = 1
-               optional_arguments = 0
-               final_argument_whitespace = True
-               option_spec = {
-                   'class': directives.class_option,
-                   'name': directives.unchanged,
-               }
-
-               def run(self):
-                   ...
-
-           def setup(app):
-               app.add_directive('my-directive', MyDirective)
-
-        For more details, see `the Docutils docs
-        <https://docutils.sourceforge.io/docs/howto/rst-directives.html>`__ .
-
-        .. versionchanged:: 0.6
-           Docutils 0.5-style directive classes are now supported.
-        .. deprecated:: 1.8
-           Docutils 0.4-style (function based) directives support is deprecated.
-        .. versionchanged:: 1.8
-           Add *override* keyword.
-        """
-        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')
-
-        docutils.register_directive(name, cls)
-
-    def add_role(self, name: str, role: Any, override: bool = False) -> None:
-        """Register a Docutils role.
-
-        :param name: The name of role
-        :param role: A role function
-        :param override: If false, do not install it if another role
-                         is already installed as the same name
-                         If true, unconditionally install the role.
-
-        For more details about role functions, see `the Docutils docs
-        <https://docutils.sourceforge.io/docs/howto/rst-roles.html>`__ .
-
-        .. versionchanged:: 1.8
-           Add *override* keyword.
-        """
-        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')
-        docutils.register_role(name, role)
-
-    def add_generic_role(self, name: str, nodeclass: Any, override: bool = False) -> None:
-        """Register a generic Docutils role.
-
-        Register a Docutils role that does nothing but wrap its contents in the
-        node given by *nodeclass*.
-
-        :param override: If false, do not install it if another role
-                         is already installed as the same name
-                         If true, unconditionally install the role.
-
-        .. versionadded:: 0.6
-        .. versionchanged:: 1.8
-           Add *override* keyword.
-        """
-        # Don't use ``roles.register_generic_role`` because it uses
-        # ``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')
-        role = roles.GenericRole(name, nodeclass)
-        docutils.register_role(name, role)
-
-    def add_domain(self, domain: type[Domain], override: bool = False) -> None:
-        """Register a domain.
-
-        :param domain: A domain class
-        :param override: If false, do not install it if another domain
-                         is already installed as the same name
-                         If true, unconditionally install the domain.
-
-        .. versionadded:: 1.0
-        .. versionchanged:: 1.8
-           Add *override* keyword.
-        """
-        self.registry.add_domain(domain, override=override)
-
-    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
-        named *domain*.
-
-        :param domain: The name of target domain
-        :param name: A name of directive
-        :param cls: A directive class
-        :param override: If false, do not install it if another directive
-                         is already installed as the same name
-                         If true, unconditionally install the directive.
-
-        .. versionadded:: 1.0
-        .. versionchanged:: 1.8
-           Add *override* keyword.
-        """
-        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:
-        """Register a Docutils role in a domain.
-
-        Like :meth:`add_role`, but the role is added to the domain named
-        *domain*.
-
-        :param domain: The name of the target domain
-        :param name: The name of the role
-        :param role: The role function
-        :param override: If false, do not install it if another role
-                         is already installed as the same name
-                         If true, unconditionally install the role.
-
-        .. versionadded:: 1.0
-        .. versionchanged:: 1.8
-           Add *override* keyword.
-        """
-        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:
-        """Register a custom index for a domain.
-
-        Add a custom *index* class to the domain named *domain*.
-
-        :param domain: The name of the target domain
-        :param index: The index class
-        :param override: If false, do not install it if another index
-                         is already installed as the same name
-                         If true, unconditionally install the index.
-
-        .. versionadded:: 1.0
-        .. versionchanged:: 1.8
-           Add *override* keyword.
-        """
-        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[TextElement] | None = None,
-                        objname: str = '', doc_field_types: list = [], override: bool = False
-                        ) -> None:
-        """Register a new object type.
-
-        This method is a very convenient way to add a new :term:`object` type
-        that can be cross-referenced.  It will do this:
-
-        - Create a new directive (called *directivename*) for documenting an
-          object.  It will automatically add index entries if *indextemplate*
-          is nonempty; if given, it must contain exactly one instance of
-          ``%s``.  See the example below for how the template will be
-          interpreted.
-        - Create a new role (called *rolename*) to cross-reference to these
-          object descriptions.
-        - If you provide *parse_node*, it must be a function that takes a
-          string and a docutils node, and it must populate the node with
-          children parsed from the string.  It must then return the name of the
-          item to be used in cross-referencing and index entries.  See the
-          :file:`conf.py` file in the source for this documentation for an
-          example.
-        - The *objname* (if not given, will default to *directivename*) names
-          the type of object.  It is used when listing objects, e.g. in search
-          results.
-
-        For example, if you have this call in a custom Sphinx extension::
-
-           app.add_object_type('directive', 'dir', 'pair: %s; directive')
-
-        you can use this markup in your documents::
-
-           .. rst:directive:: function
-
-              Document a function.
-
-           <...>
-
-           See also the :rst:dir:`function` directive.
-
-        For the directive, an index entry will be generated as if you had prepended ::
-
-           .. index:: pair: function; directive
-
-        The reference node will be of class ``literal`` (so it will be rendered
-        in a proportional font, as appropriate for code) unless you give the
-        *ref_nodeclass* argument, which must be a docutils node class.  Most
-        useful are ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` --
-        you can also use ``docutils.nodes.generated`` if you want no further
-        text decoration.  If the text should be treated as literal (e.g. no
-        smart quote replacement), but not have typewriter styling, use
-        ``sphinx.addnodes.literal_emphasis`` or
-        ``sphinx.addnodes.literal_strong``.
-
-        For the role content, you have the same syntactical possibilities as
-        for standard Sphinx roles (see :ref:`xref-syntax`).
-
-        If *override* is True, the given object_type is forcedly installed even if
-        an object_type having the same name is already installed.
-
-        .. versionchanged:: 1.8
-           Add *override* keyword.
-        """
-        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[TextElement] | None = None, objname: str = '',
-                          override: bool = False) -> None:
-        """Register a new crossref object type.
-
-        This method is very similar to :meth:`add_object_type` except that the
-        directive it generates must be empty, and will produce no output.
-
-        That means that you can add semantic targets to your sources, and refer
-        to them using custom roles instead of generic ones (like
-        :rst:role:`ref`).  Example call::
-
-           app.add_crossref_type('topic', 'topic', 'single: %s',
-                                 docutils.nodes.emphasis)
-
-        Example usage::
-
-           .. topic:: application API
-
-           The application API
-           -------------------
-
-           Some random text here.
-
-           See also :topic:`this section <application API>`.
-
-        (Of course, the element following the ``topic`` directive needn't be a
-        section.)
-
-
-        :param override: If false, do not install it if another cross-reference type
-                         is already installed as the same name
-                         If true, unconditionally install the cross-reference type.
-
-        .. versionchanged:: 1.8
-           Add *override* keyword.
-        """
-        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.
-
-        Add the standard docutils :class:`Transform` subclass *transform* to
-        the list of transforms that are applied after Sphinx parses a reST
-        document.
-
-        :param transform: A transform class
-
-        .. list-table:: priority range categories for Sphinx transforms
-           :widths: 20,80
-
-           * - Priority
-             - Main purpose in Sphinx
-           * - 0-99
-             - Fix invalid nodes by docutils. Translate a doctree.
-           * - 100-299
-             - Preparation
-           * - 300-399
-             - early
-           * - 400-699
-             - main
-           * - 700-799
-             - Post processing. Deadline to modify text and referencing.
-           * - 800-899
-             - Collect referencing and referenced nodes. Domain processing.
-           * - 900-999
-             - Finalize and clean up.
-
-        refs: `Transform Priority Range Categories`__
-
-        __ https://docutils.sourceforge.io/docs/ref/transforms.html#transform-priority-range-categories
-        """  # noqa: E501
-        self.registry.add_transform(transform)
-
-    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
-        the list of transforms that are applied before Sphinx writes a
-        document.
-
-        :param transform: A transform class
-        """
-        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:
-        """Register a JavaScript file to include in the HTML output.
-
-        :param filename: The name of a JavaScript file that the default HTML
-                         template will include. It must be relative to the HTML
-                         static path, or a full URI with scheme, or ``None`` .
-                         The ``None`` value is used to create an inline
-                         ``<script>`` tag.  See the description of *kwargs*
-                         below.
-        :param priority: Files are included in ascending order of priority. If
-                         multiple JavaScript files have the same priority,
-                         those files will be included in order of registration.
-                         See list of "prority range for JavaScript files" below.
-        :param loading_method: The loading method for the JavaScript file.
-                               Either ``'async'`` or ``'defer'`` are allowed.
-        :param kwargs: Extra keyword arguments are included as attributes of the
-                       ``<script>`` tag.  If the special keyword argument
-                       ``body`` is given, its value will be added as the content
-                       of the  ``<script>`` tag.
-
-        Example::
-
-            app.add_js_file('example.js')
-            # => <script src="_static/example.js"></script>
-
-            app.add_js_file('example.js', loading_method="async")
-            # => <script src="_static/example.js" async="async"></script>
-
-            app.add_js_file(None, body="var myVariable = 'foo';")
-            # => <script>var myVariable = 'foo';</script>
-
-        .. list-table:: priority range for JavaScript files
-           :widths: 20,80
-
-           * - Priority
-             - Main purpose in Sphinx
-           * - 200
-             - default priority for built-in JavaScript files
-           * - 500
-             - default priority for extensions
-           * - 800
-             - default priority for :confval:`html_js_files`
-
-        A JavaScript file can be added to the specific HTML page when an extension
-        calls this method on :event:`html-page-context` event.
-
-        .. versionadded:: 0.5
-
-        .. versionchanged:: 1.8
-           Renamed from ``app.add_javascript()``.
-           And it allows keyword arguments as attributes of script tag.
-
-        .. versionchanged:: 3.5
-           Take priority argument.  Allow to add a JavaScript file to the specific page.
-        .. versionchanged:: 4.4
-           Take loading_method argument.  Allow to change the loading method of the
-           JavaScript file.
-        """
-        if loading_method == 'async':
-            kwargs['async'] = 'async'
-        elif loading_method == 'defer':
-            kwargs['defer'] = 'defer'
-
-        self.registry.add_js_file(filename, priority=priority, **kwargs)
-        if hasattr(self, 'builder') and hasattr(self.builder, 'add_js_file'):
-            self.builder.add_js_file(filename,
-                                     priority=priority, **kwargs)
-
-    def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None:
-        """Register a stylesheet to include in the HTML output.
-
-        :param filename: The name of a CSS file that the default HTML
-                         template will include. It must be relative to the HTML
-                         static path, or a full URI with scheme.
-        :param priority: Files are included in ascending order of priority. If
-                         multiple CSS files have the same priority,
-                         those files will be included in order of registration.
-                         See list of "prority range for CSS files" below.
-        :param kwargs: Extra keyword arguments are included as attributes of the
-                       ``<link>`` tag.
-
-        Example::
-
-            app.add_css_file('custom.css')
-            # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
-
-            app.add_css_file('print.css', media='print')
-            # => <link rel="stylesheet" href="_static/print.css"
-            #          type="text/css" media="print" />
-
-            app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
-            # => <link rel="alternate stylesheet" href="_static/fancy.css"
-            #          type="text/css" title="fancy" />
-
-        .. list-table:: priority range for CSS files
-           :widths: 20,80
-
-           * - Priority
-             - Main purpose in Sphinx
-           * - 200
-             - default priority for built-in CSS files
-           * - 500
-             - default priority for extensions
-           * - 800
-             - default priority for :confval:`html_css_files`
-
-        A CSS file can be added to the specific HTML page when an extension calls
-        this method on :event:`html-page-context` event.
-
-        .. versionadded:: 1.0
-
-        .. versionchanged:: 1.6
-           Optional ``alternate`` and/or ``title`` attributes can be supplied
-           with the arguments *alternate* (a Boolean) and *title* (a string).
-           The default is no title and *alternate* = ``False``. For
-           more information, refer to the `documentation
-           <https://mdn.io/Web/CSS/Alternative_style_sheets>`__.
-
-        .. versionchanged:: 1.8
-           Renamed from ``app.add_stylesheet()``.
-           And it allows keyword arguments as attributes of link tag.
-
-        .. versionchanged:: 3.5
-           Take priority argument.  Allow to add a CSS file to the specific page.
-        """
-        logger.debug('[app] adding stylesheet: %r', filename)
-        self.registry.add_css_files(filename, priority=priority, **kwargs)
-        if hasattr(self, 'builder') and hasattr(self.builder, 'add_css_file'):
-            self.builder.add_css_file(filename,
-                                      priority=priority, **kwargs)
-
-    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
-        include.  If you provide *options*, it will be taken to the `\usepackage`
-        declaration.  If you set *after_hyperref* truthy, the package will be
-        loaded after ``hyperref`` package.
-
-        .. code-block:: python
-
-           app.add_latex_package('mypackage')
-           # => \usepackage{mypackage}
-           app.add_latex_package('mypackage', 'foo,bar')
-           # => \usepackage[foo,bar]{mypackage}
-
-        .. versionadded:: 1.3
-        .. versionadded:: 3.1
-
-           *after_hyperref* option.
-        """
-        self.registry.add_latex_package(packagename, options, after_hyperref)
-
-    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*.
-
-        .. versionadded:: 0.6
-        .. versionchanged:: 2.1
-           Take a lexer class as an argument.  An instance of lexers are
-           still supported until Sphinx-3.x.
-        """
-        logger.debug('[app] adding lexer: %r', (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.
-
-        Add *cls* as a new documenter class for the :mod:`sphinx.ext.autodoc`
-        extension.  It must be a subclass of
-        :class:`sphinx.ext.autodoc.Documenter`.  This allows auto-documenting
-        new types of objects.  See the source of the autodoc module for
-        examples on how to subclass :class:`Documenter`.
-
-        If *override* is True, the given *cls* is forcedly installed even if
-        a documenter having the same name is already installed.
-
-        See :ref:`autodoc_ext_tutorial`.
-
-        .. versionadded:: 0.6
-        .. versionchanged:: 2.2
-           Add *override* keyword.
-        """
-        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:
-        """Register a new ``getattr``-like function for the autodoc extension.
-
-        Add *getter*, which must be a function with an interface compatible to
-        the :func:`getattr` builtin, as the autodoc attribute getter for
-        objects that are instances of *typ*.  All cases where autodoc needs to
-        get an attribute of a type are then handled by this function instead of
-        :func:`getattr`.
-
-        .. versionadded:: 0.6
-        """
-        logger.debug('[app] adding autodoc attrgetter: %r', (typ, getter))
-        self.registry.add_autodoc_attrgetter(typ, getter)
-
-    def add_search_language(self, cls: Any) -> None:
-        """Register a new language for the HTML search index.
-
-        Add *cls*, which must be a subclass of
-        :class:`sphinx.search.SearchLanguage`, as a support language for
-        building the HTML full-text search index.  The class must have a *lang*
-        attribute that indicates the language it should be used for.  See
-        :confval:`html_search_language`.
-
-        .. versionadded:: 1.1
-        """
-        logger.debug('[app] adding search language: %r', cls)
-        from sphinx.search import SearchLanguage, languages
-        assert issubclass(cls, SearchLanguage)
-        languages[cls.lang] = cls
-
-    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
-        using the config setting.
-
-        :param override: If false, do not install it the same suffix
-                         is already installed.
-                         If true, unconditionally install the suffix.
-
-        .. versionadded:: 1.8
-        """
-        self.registry.add_source_suffix(suffix, filetype, override=override)
-
-    def add_source_parser(self, parser: type[Parser], override: bool = False) -> None:
-        """Register a parser class.
-
-        :param override: If false, do not install it if another parser
-                         is already installed for the same suffix.
-                         If true, unconditionally install the parser.
-
-        .. versionadded:: 1.4
-        .. versionchanged:: 1.8
-           *suffix* argument is deprecated.  It only accepts *parser* argument.
-           Use :meth:`add_source_suffix` API to register suffix instead.
-        .. versionchanged:: 1.8
-           Add *override* keyword.
-        """
-        self.registry.add_source_parser(parser, override=override)
-
-    def add_env_collector(self, collector: type[EnvironmentCollector]) -> None:
-        """Register an environment collector class.
-
-        Refer to :ref:`collector-api`.
-
-        .. versionadded:: 1.6
-        """
-        logger.debug('[app] adding environment collector: %r', collector)
-        collector().enable(self)
-
-    def add_html_theme(self, name: str, theme_path: str) -> None:
-        """Register a HTML Theme.
-
-        The *name* is a name of theme, and *theme_path* is a full path to the
-        theme (refs: :ref:`distribute-your-theme`).
-
-        .. versionadded:: 1.6
-        """
-        logger.debug('[app] adding HTML theme: %r, %r', name, theme_path)
-        self.registry.add_html_theme(name, theme_path)
-
-    def add_html_math_renderer(self, name: str,
-                               inline_renderers: tuple[Callable, Callable] = None,
-                               block_renderers: tuple[Callable, Callable] = None) -> None:
-        """Register a math renderer for HTML.
-
-        The *name* is a name of math renderer.  Both *inline_renderers* and
-        *block_renderers* are used as visitor functions for the HTML writer:
-        the former for inline math node (``nodes.math``), the latter for
-        block math node (``nodes.math_block``).  Regarding visitor functions,
-        see :meth:`add_node` for details.
-
-        .. versionadded:: 1.8
-
-        """
-        self.registry.add_html_math_renderer(name, inline_renderers, block_renderers)
-
-    def add_message_catalog(self, catalog: str, locale_dir: str) -> None:
-        """Register a message catalog.
-
-        :param catalog: The name of the catalog
-        :param locale_dir: The base path of the message catalog
-
-        For more details, see :func:`sphinx.locale.get_translation()`.
-
-        .. versionadded:: 1.8
-        """
-        locale.init([locale_dir], self.config.language, catalog)
-        locale.init_console(locale_dir, catalog)
-
-    # ---- other methods -------------------------------------------------
-    def is_parallel_allowed(self, typ: str) -> bool:
-        """Check whether parallel processing is allowed or not.
-
-        :param typ: A type of processing; ``'read'`` or ``'write'``.
-        """
-        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")
-        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")
-        else:
-            raise ValueError('parallel type %s is not supported' % typ)
-
-        for ext in self.extensions.values():
-            allowed = getattr(ext, attrname, None)
-            if allowed is None:
-                logger.warning(message_not_declared, ext.name)
-                logger.warning(__('doing serial %s'), typ)
-                return False
-            elif not allowed:
-                logger.warning(message_not_safe, ext.name)
-                logger.warning(__('doing serial %s'), typ)
-                return False
-
-        return True
-
-    def set_html_assets_policy(self, policy):
-        """Set the policy to include assets in HTML pages.
-
-        - always: include the assets in all the pages
-        - per_page: include the assets only in pages where they are used
-
-        .. versionadded: 4.1
-        """
-        if policy not in ('always', 'per_page'):
-            raise ValueError('policy %s is not supported' % policy)
-        self.registry.html_assets_policy = policy
-
-
-class TemplateBridge:
-    """
-    This class defines the interface for a "template bridge", that is, a class
-    that renders templates given a template name and a context.
-    """
-
-    def init(
-        self,
-        builder: Builder,
-        theme: Theme | None = None,
-        dirs: list[str] | None = None
-    ) -> None:
-        """Called by the builder to initialize the template system.
-
-        *builder* is the builder object; you'll probably want to look at the
-        value of ``builder.config.templates_path``.
-
-        *theme* is a :class:`sphinx.theming.Theme` object or None; in the latter
-        case, *dirs* can be list of fixed directories to look for templates.
-        """
-        raise NotImplementedError('must be implemented in subclasses')
-
-    def newest_template_mtime(self) -> float:
-        """Called by the builder to determine if output files are outdated
-        because of template changes.  Return the mtime of the newest template
-        file that was changed.  The default implementation returns ``0``.
-        """
-        return 0
-
-    def render(self, template: str, context: dict) -> None:
-        """Called by the builder to render a template given as a filename with
-        a specified context (a Python dictionary).
-        """
-        raise NotImplementedError('must be implemented in subclasses')
-
-    def render_string(self, template: str, context: dict) -> str:
-        """Called by the builder to render a template given as a string with a
-        specified context (a Python dictionary).
-        """
-        raise NotImplementedError('must be implemented in subclasses')