Sphinx 7.1.1__py3-none-any.whl → 7.2.0__py3-none-any.whl

sphinx/cmd/make_mode.py

@@ -13,10 +13,16 @@ import os
 import subprocess
 import sys
 from os import path
+from typing import TYPE_CHECKING
 
 import sphinx
 from sphinx.cmd.build import build_main
-from sphinx.util.console import blue, bold, color_terminal, nocolor  # type: ignore
+from sphinx.util.console import (  # type: ignore[attr-defined]
+    blue,
+    bold,
+    color_terminal,
+    nocolor,
+)
 from sphinx.util.osutil import rmtree
 
 try:
@@ -24,6 +30,9 @@ try:
 except ImportError:
     from sphinx.util.osutil import _chdir as chdir
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
 BUILDERS = [
     ("",      "html",        "to make standalone HTML files"),
     ("",      "dirhtml",     "to make HTML files named index.html in directories"),
@@ -54,10 +63,10 @@ BUILDERS = [
 
 
 class Make:
-    def __init__(self, srcdir: str, builddir: str, opts: list[str]) -> None:
+    def __init__(self, srcdir: str, builddir: str, opts: Sequence[str]) -> None:
         self.srcdir = srcdir
         self.builddir = builddir
-        self.opts = opts
+        self.opts = [*opts]
         self.makecmd = os.environ.get('MAKE', 'make')  # refer $MAKE to determine make command
 
     def builddir_join(self, *comps: str) -> str:
@@ -154,7 +163,7 @@ class Make:
         return build_main(args + opts)
 
 
-def run_make_mode(args: list[str]) -> int:
+def run_make_mode(args: Sequence[str]) -> int:
     if len(args) < 3:
         print('Error: at least 3 arguments (builder, source '
               'dir, build dir) are required.', file=sys.stderr)

sphinx/cmd/quickstart.py

@@ -31,10 +31,19 @@ from docutils.utils import column_width
 import sphinx.locale
 from sphinx import __display_version__, package_dir
 from sphinx.locale import __
-from sphinx.util.console import bold, color_terminal, colorize, nocolor, red  # type: ignore
+from sphinx.util.console import (  # type: ignore[attr-defined]
+    bold,
+    color_terminal,
+    colorize,
+    nocolor,
+    red,
+)
 from sphinx.util.osutil import ensuredir
 from sphinx.util.template import SphinxRenderer
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
 EXTENSIONS = {
     'autodoc': __('automatically insert docstrings from modules'),
     'doctest': __('automatically test code snippets in doctest blocks'),
@@ -539,7 +548,7 @@ def get_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def main(argv: list[str] = sys.argv[1:]) -> int:
+def main(argv: Sequence[str] = (), /) -> int:
     locale.setlocale(locale.LC_ALL, '')
     sphinx.locale.init_console()
 
@@ -549,7 +558,7 @@ def main(argv: list[str] = sys.argv[1:]) -> int:
     # parse options
     parser = get_parser()
     try:
-        args = parser.parse_args(argv)
+        args = parser.parse_args(argv or sys.argv[1:])
     except SystemExit as err:
         return err.code  # type: ignore[return-value]
 
@@ -605,4 +614,4 @@ def main(argv: list[str] = sys.argv[1:]) -> int:
 
 
 if __name__ == '__main__':
-    raise SystemExit(main())
+    raise SystemExit(main(sys.argv[1:]))

sphinx/config.py

@@ -6,13 +6,12 @@ import time
 import traceback
 import types
 from os import getenv, path
-from typing import TYPE_CHECKING, Any, Callable, Generator, Iterator, NamedTuple
+from typing import TYPE_CHECKING, Any, Callable, NamedTuple
 
 from sphinx.errors import ConfigError, ExtensionError
 from sphinx.locale import _, __
 from sphinx.util import logging
 from sphinx.util.osutil import fs_encoding
-from sphinx.util.tags import Tags
 from sphinx.util.typing import NoneType
 
 try:
@@ -21,10 +20,12 @@ except ImportError:
     from sphinx.util.osutil import _chdir as chdir
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    import os
+    from collections.abc import Generator, Iterator, Sequence
 
     from sphinx.application import Sphinx
     from sphinx.environment import BuildEnvironment
+    from sphinx.util.tags import Tags
 
 logger = logging.getLogger(__name__)
 
@@ -58,7 +59,7 @@ class ENUM:
     Example:
         app.add_config_value('latex_show_urls', 'no', None, ENUM('no', 'footnote', 'inline'))
     """
-    def __init__(self, *candidates: str | bool) -> None:
+    def __init__(self, *candidates: str | bool | None) -> None:
         self.candidates = candidates
 
     def match(self, value: str | list | tuple) -> bool:
@@ -154,8 +155,10 @@ class Config:
         'option_emphasise_placeholders': (False, 'env', []),
     }
 
-    def __init__(self, config: dict[str, Any] = {}, overrides: dict[str, Any] = {}) -> None:
-        self.overrides = dict(overrides)
+    def __init__(self, config: dict[str, Any] | None = None,
+                 overrides: dict[str, Any] | None = None) -> None:
+        config = config or {}
+        self.overrides = dict(overrides) if overrides is not None else {}
         self.values = Config.config_values.copy()
         self._raw_config = config
         self.setup: Callable | None = config.get('setup', None)
@@ -168,9 +171,8 @@ class Config:
         self.extensions: list[str] = config.get('extensions', [])
 
     @classmethod
-    def read(
-        cls, confdir: str, overrides: dict | None = None, tags: Tags | None = None,
-    ) -> Config:
+    def read(cls, confdir: str | os.PathLike[str], overrides: dict | None = None,
+             tags: Tags | None = None) -> Config:
         """Create a Config object from configuration file."""
         filename = path.join(confdir, CONFIG_FILENAME)
         if not path.isfile(filename):
@@ -310,7 +312,7 @@ class Config:
             raise ExtensionError(__('Config value %r already present') % name)
         self.values[name] = (default, rebuild, types)
 
-    def filter(self, rebuild: str | list[str]) -> Iterator[ConfigValue]:
+    def filter(self, rebuild: str | Sequence[str]) -> Iterator[ConfigValue]:
         if isinstance(rebuild, str):
             rebuild = [rebuild]
         return (value for value in self if value.rebuild in rebuild)
@@ -402,7 +404,8 @@ def convert_highlight_options(app: Sphinx, config: Config) -> None:
     options = config.highlight_options
     if options and not all(isinstance(v, dict) for v in options.values()):
         # old styled option detected because all values are not dictionary.
-        config.highlight_options = {config.highlight_language: options}  # type: ignore
+        config.highlight_options = {config.highlight_language:  # type: ignore[attr-defined]
+                                    options}
 
 
 def init_numfig_format(app: Sphinx, config: Config) -> None:
@@ -414,7 +417,7 @@ def init_numfig_format(app: Sphinx, config: Config) -> None:
 
     # override default labels by configuration
     numfig_format.update(config.numfig_format)
-    config.numfig_format = numfig_format  # type: ignore
+    config.numfig_format = numfig_format  # type: ignore[attr-defined]
 
 
 def correct_copyright_year(_app: Sphinx, config: Config) -> None:
@@ -523,7 +526,7 @@ def check_primary_domain(app: Sphinx, config: Config) -> None:
     primary_domain = config.primary_domain
     if primary_domain and not app.registry.has_domain(primary_domain):
         logger.warning(__('primary_domain %r not found, ignored.'), primary_domain)
-        config.primary_domain = None  # type: ignore
+        config.primary_domain = None  # type: ignore[attr-defined]
 
 
 def check_root_doc(app: Sphinx, env: BuildEnvironment, added: set[str],
@@ -536,7 +539,7 @@ def check_root_doc(app: Sphinx, env: BuildEnvironment, added: set[str],
             'contents' in app.project.docnames):
         logger.warning(__('Since v2.0, Sphinx uses "index" as root_doc by default. '
                           'Please add "root_doc = \'contents\'" to your conf.py.'))
-        app.config.root_doc = "contents"  # type: ignore
+        app.config.root_doc = "contents"  # type: ignore[attr-defined]
 
     return changed
 

sphinx/deprecation.py

@@ -37,7 +37,8 @@ def _deprecation_warning(
 
        def __getattr__(name):
            if name not in _DEPRECATED_OBJECTS:
-               raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+               msg = f'module {__name__!r} has no attribute {name!r}'
+               raise AttributeError(msg)
 
            from sphinx.deprecation import _deprecation_warning
 
@@ -51,7 +52,8 @@ def _deprecation_warning(
     elif remove == (9, 0):
         warning_class = RemovedInSphinx90Warning
     else:
-        raise RuntimeError(f'removal version {remove!r} is invalid!')
+        msg = f'removal version {remove!r} is invalid!'
+        raise RuntimeError(msg)
 
     qualified_name = f'{module}.{attribute}'
     if canonical_name:

sphinx/directives/__init__.py

@@ -3,21 +3,22 @@
 from __future__ import annotations
 
 import re
-from typing import TYPE_CHECKING, Any, Generic, List, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast
 
 from docutils import nodes
-from docutils.nodes import Node
 from docutils.parsers.rst import directives, roles
 
 from sphinx import addnodes
-from sphinx.addnodes import desc_signature
+from sphinx.addnodes import desc_signature  # NoQA: TCH001
 from sphinx.util import docutils
 from sphinx.util.docfields import DocFieldTransformer, Field, TypedField
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import nested_parse_with_titles
-from sphinx.util.typing import OptionSpec
+from sphinx.util.typing import OptionSpec  # NoQA: TCH001
 
 if TYPE_CHECKING:
+    from docutils.nodes import Node
+
     from sphinx.application import Sphinx
 
 
@@ -35,7 +36,8 @@ def optional_int(argument: str) -> int | None:
     else:
         value = int(argument)
         if value < 0:
-            raise ValueError('negative value; must be positive or zero')
+            msg = 'negative value; must be positive or zero'
+            raise ValueError(msg)
         return value
 
 
@@ -54,6 +56,10 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
     optional_arguments = 0
     final_argument_whitespace = True
     option_spec: OptionSpec = {
+        'no-index': directives.flag,
+        'no-index-entry': directives.flag,
+        'no-contents-entry': directives.flag,
+        'no-typesetting': directives.flag,
         'noindex': directives.flag,
         'noindexentry': directives.flag,
         'nocontentsentry': directives.flag,
@@ -185,7 +191,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
 
         * find out if called as a domain-specific directive, set self.domain
         * create a `desc` node to fit all description inside
-        * parse standard options, currently `noindex`
+        * parse standard options, currently `no-index`
         * create an index node if needed as self.indexnode
         * parse all given signatures (as returned by self.get_signatures())
           using self.handle_signature(), which should either return a name
@@ -215,9 +221,22 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
         node['domain'] = self.domain
         # 'desctype' is a backwards compatible attribute
         node['objtype'] = node['desctype'] = self.objtype
-        node['noindex'] = noindex = ('noindex' in self.options)
-        node['noindexentry'] = ('noindexentry' in self.options)
-        node['nocontentsentry'] = ('nocontentsentry' in self.options)
+        node['no-index'] = node['noindex'] = no_index = (
+            'no-index' in self.options
+            # xref RemovedInSphinx90Warning
+            # deprecate noindex in Sphinx 9.0
+            or 'noindex' in self.options)
+        node['no-index-entry'] = node['noindexentry'] = (
+            'no-index-entry' in self.options
+            # xref RemovedInSphinx90Warning
+            # deprecate noindexentry in Sphinx 9.0
+            or 'noindexentry' in self.options)
+        node['no-contents-entry'] = node['nocontentsentry'] = (
+            'no-contents-entry' in self.options
+            # xref RemovedInSphinx90Warning
+            # deprecate nocontentsentry in Sphinx 9.0
+            or 'nocontentsentry' in self.options)
+        node['no-typesetting'] = ('no-typesetting' in self.options)
         if self.domain:
             node['classes'].append(self.domain)
         node['classes'].append(node['objtype'])
@@ -251,7 +270,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
                     signode['_toc_name'] = ''
             if name not in self.names:
                 self.names.append(name)
-                if not noindex:
+                if not no_index:
                     # only add target and index entry if this is the first
                     # description of the object with this name in this desc block
                     self.add_target_and_index(name, sig, signode)
@@ -270,6 +289,19 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
         DocFieldTransformer(self).transform_all(contentnode)
         self.env.temp_data['object'] = None
         self.after_content()
+
+        if node['no-typesetting']:
+            # Attempt to return the index node, and a new target node
+            # containing all the ids of this node and its children.
+            # If ``:no-index:`` is set, or there are no ids on the node
+            # or any of its children, then just return the index node,
+            # as Docutils expects a target node to have at least one id.
+            if node_ids := [node_id for el in node.findall(nodes.Element)
+                            for node_id in el.get('ids', ())]:
+                target_node = nodes.target(ids=node_ids)
+                self.set_source_info(target_node)
+                return [self.indexnode, target_node]
+            return [self.indexnode]
         return [self.indexnode, node]
 
 
@@ -289,7 +321,7 @@ class DefaultRole(SphinxDirective):
         role, messages = roles.role(role_name, self.state_machine.language,
                                     self.lineno, self.state.reporter)
         if role:  # type: ignore[truthy-function]
-            docutils.register_role('', role)
+            docutils.register_role('', role)  # type: ignore[arg-type]
             self.env.temp_data['default_role'] = role_name
         else:
             literal_block = nodes.literal_block(self.block_text, self.block_text)
@@ -298,7 +330,7 @@ class DefaultRole(SphinxDirective):
                                    literal_block, line=self.lineno)
             messages += [error]
 
-        return cast(List[nodes.Node], messages)
+        return cast(list[nodes.Node], messages)
 
 
 class DefaultDomain(SphinxDirective):

sphinx/directives/code.py

@@ -6,20 +6,21 @@ from difflib import unified_diff
 from typing import TYPE_CHECKING, Any
 
 from docutils import nodes
-from docutils.nodes import Element, Node
 from docutils.parsers.rst import directives
 from docutils.statemachine import StringList
 
 from sphinx import addnodes
-from sphinx.config import Config
 from sphinx.directives import optional_int
 from sphinx.locale import __
 from sphinx.util import logging, parselinenos
 from sphinx.util.docutils import SphinxDirective
-from sphinx.util.typing import OptionSpec
 
 if TYPE_CHECKING:
+    from docutils.nodes import Element, Node
+
     from sphinx.application import Sphinx
+    from sphinx.config import Config
+    from sphinx.util.typing import OptionSpec
 
 logger = logging.getLogger(__name__)
 
@@ -244,7 +245,7 @@ class LiteralIncludeReader:
         new_lines = self.read_file(self.filename)
         old_filename = self.options['diff']
         old_lines = self.read_file(old_filename)
-        diff = unified_diff(old_lines, new_lines, old_filename, self.filename)
+        diff = unified_diff(old_lines, new_lines, str(old_filename), str(self.filename))
         return list(diff)
 
     def pyobject_filter(

sphinx/directives/other.py

@@ -4,23 +4,27 @@ import re
 from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
-from docutils.nodes import Element, Node
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives.admonitions import BaseAdmonition
 from docutils.parsers.rst.directives.misc import Class
 from docutils.parsers.rst.directives.misc import Include as BaseInclude
+from docutils.statemachine import StateMachine
 
 from sphinx import addnodes
 from sphinx.domains.changeset import VersionChange  # noqa: F401  # for compatibility
+from sphinx.domains.std import StandardDomain
 from sphinx.locale import _, __
 from sphinx.util import docname_join, logging, url_re
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.matching import Matcher, patfilter
 from sphinx.util.nodes import explicit_title_re
-from sphinx.util.typing import OptionSpec
+from sphinx.util.osutil import os_path
 
 if TYPE_CHECKING:
+    from docutils.nodes import Element, Node
+
     from sphinx.application import Sphinx
+    from sphinx.util.typing import OptionSpec
 
 
 glob_re = re.compile(r'.*[*?\[].*')
@@ -79,71 +83,81 @@ class TocTree(SphinxDirective):
         return ret
 
     def parse_content(self, toctree: addnodes.toctree) -> list[Node]:
-        generated_docnames = frozenset(self.env.domains['std']._virtual_doc_names)
+        generated_docnames = frozenset(StandardDomain._virtual_doc_names)
         suffixes = self.config.source_suffix
+        current_docname = self.env.docname
+        glob = toctree['glob']
 
         # glob target documents
         all_docnames = self.env.found_docs.copy() | generated_docnames
-        all_docnames.remove(self.env.docname)  # remove current document
+        all_docnames.remove(current_docname)  # remove current document
+        frozen_all_docnames = frozenset(all_docnames)
 
         ret: list[Node] = []
         excluded = Matcher(self.config.exclude_patterns)
         for entry in self.content:
             if not entry:
                 continue
+
             # look for explicit titles ("Some Title <document>")
             explicit = explicit_title_re.match(entry)
-            if (toctree['glob'] and glob_re.match(entry) and
-                    not explicit and not url_re.match(entry)):
-                patname = docname_join(self.env.docname, entry)
-                docnames = sorted(patfilter(all_docnames, patname))
-                for docname in docnames:
+            url_match = url_re.match(entry) is not None
+            if glob and glob_re.match(entry) and not explicit and not url_match:
+                pat_name = docname_join(current_docname, entry)
+                doc_names = sorted(patfilter(all_docnames, pat_name))
+                for docname in doc_names:
                     if docname in generated_docnames:
                         # don't include generated documents in globs
                         continue
                     all_docnames.remove(docname)  # don't include it again
                     toctree['entries'].append((None, docname))
                     toctree['includefiles'].append(docname)
-                if not docnames:
+                if not doc_names:
                     logger.warning(__("toctree glob pattern %r didn't match any documents"),
                                    entry, location=toctree)
+                continue
+
+            if explicit:
+                ref = explicit.group(2)
+                title = explicit.group(1)
+                docname = ref
             else:
-                if explicit:
-                    ref = explicit.group(2)
-                    title = explicit.group(1)
-                    docname = ref
-                else:
-                    ref = docname = entry
-                    title = None
-                # remove suffixes (backwards compatibility)
-                for suffix in suffixes:
-                    if docname.endswith(suffix):
-                        docname = docname[:-len(suffix)]
-                        break
-                # absolutize filenames
-                docname = docname_join(self.env.docname, docname)
-                if url_re.match(ref) or ref == 'self':
-                    toctree['entries'].append((title, ref))
-                elif docname not in self.env.found_docs | generated_docnames:
-                    if excluded(self.env.doc2path(docname, False)):
-                        message = __('toctree contains reference to excluded document %r')
-                        subtype = 'excluded'
-                    else:
-                        message = __('toctree contains reference to nonexisting document %r')
-                        subtype = 'not_readable'
-
-                    logger.warning(message, docname, type='toc', subtype=subtype,
-                                   location=toctree)
-                    self.env.note_reread()
+                ref = docname = entry
+                title = None
+
+            # remove suffixes (backwards compatibility)
+            for suffix in suffixes:
+                if docname.endswith(suffix):
+                    docname = docname.removesuffix(suffix)
+                    break
+
+            # absolutise filenames
+            docname = docname_join(current_docname, docname)
+            if url_match or ref == 'self':
+                toctree['entries'].append((title, ref))
+                continue
+
+            if docname not in frozen_all_docnames:
+                if excluded(self.env.doc2path(docname, False)):
+                    message = __('toctree contains reference to excluded document %r')
+                    subtype = 'excluded'
                 else:
-                    if docname in all_docnames:
-                        all_docnames.remove(docname)
-                    else:
-                        logger.warning(__('duplicated entry found in toctree: %s'), docname,
-                                       location=toctree)
+                    message = __('toctree contains reference to nonexisting document %r')
+                    subtype = 'not_readable'
 
-                    toctree['entries'].append((title, docname))
-                    toctree['includefiles'].append(docname)
+                logger.warning(message, docname, type='toc', subtype=subtype,
+                               location=toctree)
+                self.env.note_reread()
+                continue
+
+            if docname in all_docnames:
+                all_docnames.remove(docname)
+            else:
+                logger.warning(__('duplicated entry found in toctree: %s'), docname,
+                               location=toctree)
+
+            toctree['entries'].append((title, docname))
+            toctree['includefiles'].append(docname)
 
         # entries contains all entries (self references, external links etc.)
         if 'reversed' in self.options:
@@ -357,6 +371,40 @@ class Include(BaseInclude, SphinxDirective):
     """
 
     def run(self) -> list[Node]:
+
+        # To properly emit "source-read" events from included RST text,
+        # we must patch the ``StateMachine.insert_input()`` method.
+        # In the future, docutils will hopefully offer a way for Sphinx
+        # to provide the RST parser to use
+        # when parsing RST text that comes in via Include directive.
+        def _insert_input(include_lines, path):
+            # First, we need to combine the lines back into text so that
+            # we can send it with the source-read event.
+            # In docutils 0.18 and later, there are two lines at the end
+            # that act as markers.
+            # We must preserve them and leave them out of the source-read event:
+            text = "\n".join(include_lines[:-2])
+
+            # The docname to pass into the source-read event
+            docname = self.env.path2doc(os_path(path))
+            # Emit the "source-read" event
+            arg = [text]
+            self.env.app.events.emit("source-read", docname, arg)
+            text = arg[0]
+
+            # Split back into lines and reattach the two marker lines
+            include_lines = text.splitlines() + include_lines[-2:]
+
+            # Call the parent implementation.
+            # Note that this snake does not eat its tail because we patch
+            # the *Instance* method and this call is to the *Class* method.
+            return StateMachine.insert_input(self.state_machine, include_lines, path)
+
+        # Only enable this patch if there are listeners for 'source-read'.
+        if self.env.app.events.listeners.get('source-read'):
+            # See https://github.com/python/mypy/issues/2427 for details on the mypy issue
+            self.state_machine.insert_input = _insert_input  # type: ignore[method-assign]
+
         if self.arguments[0].startswith('<') and \
            self.arguments[0].endswith('>'):
             # docutils "standard" includes, do not do path processing

sphinx/directives/patches.py

@@ -18,10 +18,10 @@ from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import set_source_info
 from sphinx.util.osutil import SEP, os_path, relpath
-from sphinx.util.typing import OptionSpec
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
+    from sphinx.util.typing import OptionSpec
 
 
 logger = logging.getLogger(__name__)

sphinx/domains/__init__.py

@@ -8,23 +8,25 @@ from __future__ import annotations
 
 import copy
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any, Callable, Iterable, NamedTuple, Optional, cast
+from typing import TYPE_CHECKING, Any, Callable, NamedTuple, Optional, cast
 
-from docutils import nodes
 from docutils.nodes import Element, Node, system_message
-from docutils.parsers.rst.states import Inliner
 
-from sphinx.addnodes import pending_xref
 from sphinx.errors import SphinxError
 from sphinx.locale import _
-from sphinx.roles import XRefRole
-from sphinx.util.typing import RoleFunction
 
 if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+    from docutils import nodes
     from docutils.parsers.rst import Directive
+    from docutils.parsers.rst.states import Inliner
 
+    from sphinx.addnodes import pending_xref
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
+    from sphinx.roles import XRefRole
+    from sphinx.util.typing import RoleFunction
 
 
 class ObjType:
@@ -262,10 +264,11 @@ class Domain:
         fullname = f'{self.name}:{name}'
 
         def role_adapter(typ: str, rawtext: str, text: str, lineno: int,
-                         inliner: Inliner, options: dict = {}, content: list[str] = [],
+                         inliner: Inliner, options: dict | None = None,
+                         content: Sequence[str] = (),
                          ) -> tuple[list[Node], list[system_message]]:
             return self.roles[name](fullname, rawtext, text, lineno,
-                                    inliner, options, content)
+                                    inliner, options or {}, content)
         self._role_cache[name] = role_adapter
         return role_adapter