"""
This type stub file was generated by pyright.
"""

from typing import Any, Callable, Final, TYPE_CHECKING
from docutils import nodes
from docutils.nodes import Element, Node, system_message
from docutils.parsers.rst import Directive, directives
from sphinx.addnodes import desc_signature, pending_xref
from sphinx.directives import ObjectDescription
from sphinx.domains import Domain, ObjType, TitleGetter
from sphinx.roles import XRefRole
from sphinx.util.docutils import SphinxDirective
from collections.abc import Iterable, Iterator
from sphinx.application import Sphinx
from sphinx.builders import Builder
from sphinx.environment import BuildEnvironment
from sphinx.util.typing import OptionSpec, RoleFunction

"""The standard domain."""
if TYPE_CHECKING:
    ...
logger = ...
option_desc_re = ...
token_re = ...
samp_role = ...
class GenericObject(ObjectDescription[str]):
    """
    A generic x-ref directive registered with Sphinx.add_object_type().
    """
    indextemplate: str = ...
    parse_node: Callable[[BuildEnvironment, str, desc_signature], str] | None = ...
    def handle_signature(self, sig: str, signode: desc_signature) -> str:
        ...
    
    def add_target_and_index(self, name: str, sig: str, signode: desc_signature) -> None:
        ...
    


class EnvVar(GenericObject):
    indextemplate = ...


class EnvVarXRefRole(XRefRole):
    """
    Cross-referencing role for environment variables (adds an index entry).
    """
    def result_nodes(self, document: nodes.document, env: BuildEnvironment, node: Element, is_ref: bool) -> tuple[list[Node], list[system_message]]:
        ...
    


class Target(SphinxDirective):
    """
    Generic target for user-defined cross-reference types.
    """
    indextemplate = ...
    has_content = ...
    required_arguments = ...
    optional_arguments = ...
    final_argument_whitespace = ...
    option_spec: OptionSpec = ...
    def run(self) -> list[Node]:
        ...
    


class Cmdoption(ObjectDescription[str]):
    """
    Description of a command-line option (.. option).
    """
    def handle_signature(self, sig: str, signode: desc_signature) -> str:
        """Transform an option description into RST nodes."""
        ...
    
    def add_target_and_index(self, firstname: str, sig: str, signode: desc_signature) -> None:
        ...
    


class Program(SphinxDirective):
    """
    Directive to name the program for which options are documented.
    """
    has_content = ...
    required_arguments = ...
    optional_arguments = ...
    final_argument_whitespace = ...
    option_spec: OptionSpec = ...
    def run(self) -> list[Node]:
        ...
    


class OptionXRefRole(XRefRole):
    def process_link(self, env: BuildEnvironment, refnode: Element, has_explicit_title: bool, title: str, target: str) -> tuple[str, str]:
        ...
    


def split_term_classifiers(line: str) -> list[str | None]:
    ...

def make_glossary_term(env: BuildEnvironment, textnodes: Iterable[Node], index_key: str, source: str, lineno: int, node_id: str | None, document: nodes.document) -> nodes.term:
    ...

class Glossary(SphinxDirective):
    """
    Directive to create a glossary with cross-reference targets for :term:
    roles.
    """
    has_content = ...
    required_arguments = ...
    optional_arguments = ...
    final_argument_whitespace = ...
    option_spec: OptionSpec = ...
    def run(self) -> list[Node]:
        ...
    


def token_xrefs(text: str, productionGroup: str = ...) -> list[Node]:
    ...

class ProductionList(SphinxDirective):
    """
    Directive to list grammar productions.
    """
    has_content = ...
    required_arguments = ...
    optional_arguments = ...
    final_argument_whitespace = ...
    option_spec: OptionSpec = ...
    def run(self) -> list[Node]:
        ...
    


class TokenXRefRole(XRefRole):
    def process_link(self, env: BuildEnvironment, refnode: Element, has_explicit_title: bool, title: str, target: str) -> tuple[str, str]:
        ...
    


class StandardDomain(Domain):
    """
    Domain for all objects that don't fit into another domain or are added
    via the application interface.
    """
    name = ...
    label = ...
    object_types: dict[str, ObjType] = ...
    directives: dict[str, type[Directive]] = ...
    roles: dict[str, RoleFunction | XRefRole] = ...
    initial_data: Final = ...
    _virtual_doc_names: dict[str, tuple[str, str]] = ...
    dangling_warnings = ...
    enumerable_nodes: dict[type[Node], tuple[str, TitleGetter | None]] = ...
    def __init__(self, env: BuildEnvironment) -> None:
        ...
    
    def note_hyperlink_target(self, name: str, docname: str, node_id: str, title: str = ...) -> None:
        """Add a hyperlink target for cross reference.

        .. warning::

           This is only for internal use.  Please don't use this from your extension.
           ``document.note_explicit_target()`` or ``note_implicit_target()`` are recommended to
           add a hyperlink target to the document.

           This only adds a hyperlink target to the StandardDomain.  And this does not add a
           node_id to node.  Therefore, it is very fragile to calling this without
           understanding hyperlink target framework in both docutils and Sphinx.

        .. versionadded:: 3.0
        """
        ...
    
    @property
    def objects(self) -> dict[tuple[str, str], tuple[str, str]]:
        ...
    
    def note_object(self, objtype: str, name: str, labelid: str, location: Any = ...) -> None:
        """Note a generic object for cross reference.

        .. versionadded:: 3.0
        """
        ...
    
    @property
    def progoptions(self) -> dict[tuple[str | None, str], tuple[str, str]]:
        ...
    
    @property
    def labels(self) -> dict[str, tuple[str, str, str]]:
        ...
    
    @property
    def anonlabels(self) -> dict[str, tuple[str, str]]:
        ...
    
    def clear_doc(self, docname: str) -> None:
        ...
    
    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None:
        ...
    
    def process_doc(self, env: BuildEnvironment, docname: str, document: nodes.document) -> None:
        ...
    
    def add_program_option(self, program: str | None, name: str, docname: str, labelid: str) -> None:
        ...
    
    def build_reference_node(self, fromdocname: str, builder: Builder, docname: str, labelid: str, sectname: str, rolename: str, **options: Any) -> Element:
        ...
    
    def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder, typ: str, target: str, node: pending_xref, contnode: Element) -> Element | None:
        ...
    
    def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder, target: str, node: pending_xref, contnode: Element) -> list[tuple[str, Element]]:
        ...
    
    def get_objects(self) -> Iterator[tuple[str, str, str, str, str, int]]:
        ...
    
    def get_type_name(self, type: ObjType, primary: bool = ...) -> str:
        ...
    
    def is_enumerable_node(self, node: Node) -> bool:
        ...
    
    def get_numfig_title(self, node: Node) -> str | None:
        """Get the title of enumerable nodes to refer them using its title"""
        ...
    
    def get_enumerable_node_type(self, node: Node) -> str | None:
        """Get type of enumerable nodes."""
        ...
    
    def get_fignumber(self, env: BuildEnvironment, builder: Builder, figtype: str, docname: str, target_node: Element) -> tuple[int, ...] | None:
        ...
    
    def get_full_qualified_name(self, node: Element) -> str | None:
        ...
    


def warn_missing_reference(app: Sphinx, domain: Domain, node: pending_xref) -> bool | None:
    ...

def setup(app: Sphinx) -> dict[str, Any]:
    ...

