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

from typing import Any, Callable, TYPE_CHECKING
from docutils import nodes
from sphinx import addnodes
from collections.abc import Iterable
from docutils.nodes import Element, Node
from docutils.parsers.rst import Directive
from docutils.parsers.rst.states import Inliner
from docutils.statemachine import StringList
from sphinx.builders import Builder
from sphinx.environment import BuildEnvironment
from sphinx.util.tags import Tags

"""Docutils node-related utility functions for Sphinx."""
if TYPE_CHECKING:
    ...
logger = ...
explicit_title_re = ...
caption_ref_re = ...
class NodeMatcher:
    """A helper class for Node.findall().

    It checks that the given node is an instance of the specified node-classes and
    has the specified node-attributes.

    For example, following example searches ``reference`` node having ``refdomain``
    and ``reftype`` attributes::

        matcher = NodeMatcher(nodes.reference, refdomain='std', reftype='citation')
        doctree.findall(matcher)
        # => [<reference ...>, <reference ...>, ...]

    A special value ``typing.Any`` matches any kind of node-attributes.  For example,
    following example searches ``reference`` node having ``refdomain`` attributes::

        from __future__ import annotations
from typing import TYPE_CHECKING, Any
        matcher = NodeMatcher(nodes.reference, refdomain=Any)
        doctree.findall(matcher)
        # => [<reference ...>, <reference ...>, ...]
    """
    def __init__(self, *node_classes: type[Node], **attrs: Any) -> None:
        ...
    
    def match(self, node: Node) -> bool:
        ...
    
    def __call__(self, node: Node) -> bool:
        ...
    


def get_full_module_name(node: Node) -> str:
    """
    Return full module dotted path like: 'docutils.nodes.paragraph'

    :param nodes.Node node: target node
    :return: full module dotted path
    """
    ...

def repr_domxml(node: Node, length: int = ...) -> str:
    """
    return DOM XML representation of the specified node like:
    '<paragraph translatable="False"><inline classes="versionmodified">New in version...'

    :param nodes.Node node: target node
    :param int length:
       length of return value to be striped. if false-value is specified, repr_domxml
       returns full of DOM XML representation.
    :return: DOM XML representation
    """
    ...

def apply_source_workaround(node: Element) -> None:
    ...

IGNORED_NODES = ...
def is_translatable(node: Node) -> bool:
    ...

LITERAL_TYPE_NODES = ...
IMAGE_TYPE_NODES = ...
def extract_messages(doctree: Element) -> Iterable[tuple[Element, str]]:
    """Extract translatable messages from a document tree."""
    ...

def get_node_source(node: Element) -> str:
    ...

def get_node_line(node: Element) -> int:
    ...

def traverse_parent(node: Element, cls: Any = ...) -> Iterable[Element]:
    ...

def get_prev_node(node: Node) -> Node | None:
    ...

def traverse_translatable_index(doctree: Element) -> Iterable[tuple[Element, list[tuple[str, str, str, str, str | None]]]]:
    """Traverse translatable index node from a document tree."""
    ...

def nested_parse_with_titles(state: Any, content: StringList, node: Node, content_offset: int = ...) -> str:
    """Version of state.nested_parse() that allows titles and does not require
    titles to have the same decoration as the calling document.

    This is useful when the parsed content comes from a completely different
    context, such as docstrings.
    """
    ...

def clean_astext(node: Element) -> str:
    """Like node.astext(), but ignore images."""
    ...

def split_explicit_title(text: str) -> tuple[bool, str, str]:
    """Split role content into title and target, if given."""
    ...

indextypes = ...
def process_index_entry(entry: str, targetid: str) -> list[tuple[str, str, str, str, str | None]]:
    ...

def inline_all_toctrees(builder: Builder, docnameset: set[str], docname: str, tree: nodes.document, colorfunc: Callable, traversed: list[str]) -> nodes.document:
    """Inline all toctrees in the *tree*.

    Record all docnames in *docnameset*, and output docnames with *colorfunc*.
    """
    ...

_non_id_chars = ...
_non_id_at_ends = ...
_non_id_translate = ...
_non_id_translate_digraphs = ...
def make_id(env: BuildEnvironment, document: nodes.document, prefix: str = ..., term: str | None = ...) -> str:
    """Generate an appropriate node_id for given *prefix* and *term*."""
    ...

def find_pending_xref_condition(node: addnodes.pending_xref, condition: str) -> Element | None:
    """Pick matched pending_xref_condition node up from the pending_xref."""
    ...

def make_refnode(builder: Builder, fromdocname: str, todocname: str, targetid: str | None, child: Node | list[Node], title: str | None = ...) -> nodes.reference:
    """Shortcut to create a reference node."""
    ...

def set_source_info(directive: Directive, node: Node) -> None:
    ...

def set_role_source_info(inliner: Inliner, lineno: int, node: Node) -> None:
    ...

def copy_source_info(src: Element, dst: Element) -> None:
    ...

NON_SMARTQUOTABLE_PARENT_NODES = ...
def is_smartquotable(node: Node) -> bool:
    """Check whether the node is smart-quotable or not."""
    ...

def process_only_nodes(document: Node, tags: Tags) -> None:
    """Filter ``only`` nodes which do not match *tags*."""
    ...

