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

import contextlib
import hashlib
import html
import os
import posixpath
import re
import sys
import time
import warnings
import docutils.readers.doctree
from __future__ import annotations
from os import path
from typing import Any, IO, TYPE_CHECKING
from urllib.parse import quote
from docutils import nodes
from docutils.core import Publisher
from docutils.frontend import OptionParser
from docutils.io import DocTreeInput, StringOutput
from docutils.utils import relative_path
from sphinx import __display_version__, package_dir, version_info as sphinx_version
from sphinx.builders import Builder
from sphinx.builders.html._assets import _CascadingStyleSheet, _JavaScript, _file_checksum
from sphinx.config import Config, ENUM
from sphinx.deprecation import _deprecation_warning
from sphinx.domains import Domain, Index, IndexEntry
from sphinx.environment.adapters.asset import ImageAdapter
from sphinx.environment.adapters.indexentries import IndexEntries
from sphinx.environment.adapters.toctree import document_toc, global_toctree_for_doc
from sphinx.errors import ConfigError, ThemeError
from sphinx.highlighting import PygmentsBridge
from sphinx.locale import _, __
from sphinx.search import js_index
from sphinx.theming import HTMLThemeFactory
from sphinx.util import isurl, logging
from sphinx.util.display import progress_message, status_iterator
from sphinx.util.docutils import new_document
from sphinx.util.fileutil import copy_asset
from sphinx.util.i18n import format_date
from sphinx.util.inventory import InventoryFile
from sphinx.util.matching import DOTFILES, Matcher, patmatch
from sphinx.util.osutil import SEP, copyfile, ensuredir, os_path, relative_uri
from sphinx.writers.html import HTMLWriter
from sphinx.writers.html5 import HTML5Translator
from collections.abc import Iterable, Iterator, Sequence
from docutils.nodes import Node
from sphinx.application import Sphinx
from sphinx.environment import BuildEnvironment
from sphinx.util.tags import Tags

"""Several HTML builders."""
if TYPE_CHECKING:
    ...
INVENTORY_FILENAME = ...
logger = ...
return_codes_re = ...
DOMAIN_INDEX_TYPE = tuple[str, type[Index], list[tuple[str, list[IndexEntry]]], bool,]
def get_stable_hash(obj: Any) -> str:
    """
    Return a stable hash for a Python data structure.  We can't just use
    the md5 of str(obj) since for example dictionary items are enumerated
    in unpredictable order due to hash randomization in newer Pythons.
    """
    ...

def convert_locale_to_language_tag(locale: str | None) -> str | None:
    """Convert a locale string to a language tag (ex. en_US -> en-US).

    refs: BCP 47 (:rfc:`5646`)
    """
    ...

class BuildInfo:
    """buildinfo file manipulator.

    HTMLBuilder and its family are storing their own envdata to ``.buildinfo``.
    This class is a manipulator for the file.
    """
    @classmethod
    def load(cls, f: IO) -> BuildInfo:
        ...
    
    def __init__(self, config: Config | None = ..., tags: Tags | None = ..., config_categories: Sequence[str] = ...) -> None:
        ...
    
    def __eq__(self, other: BuildInfo) -> bool:
        ...
    
    def dump(self, f: IO) -> None:
        ...
    


class StandaloneHTMLBuilder(Builder):
    """
    Builds standalone HTML docs.
    """
    name = ...
    format = ...
    epilog = ...
    default_translator_class = HTML5Translator
    copysource = ...
    allow_parallel = ...
    out_suffix = ...
    link_suffix = ...
    indexer_format: Any = ...
    indexer_dumps_unicode = ...
    html_scaled_image_link = ...
    supported_image_types = ...
    supported_remote_images = ...
    supported_data_uri_images = ...
    searchindex_filename = ...
    add_permalinks = ...
    allow_sharp_as_current_path = ...
    embedded = ...
    search = ...
    use_index = ...
    download_support = ...
    imgpath: str = ...
    domain_indices: list[DOMAIN_INDEX_TYPE] = ...
    def __init__(self, app: Sphinx, env: BuildEnvironment) -> None:
        ...
    
    def init(self) -> None:
        ...
    
    def create_build_info(self) -> BuildInfo:
        ...
    
    def get_theme_config(self) -> tuple[str, dict]:
        ...
    
    def init_templates(self) -> None:
        ...
    
    def init_highlighter(self) -> None:
        ...
    
    @property
    def css_files(self) -> list[_CascadingStyleSheet]:
        ...
    
    def init_css_files(self) -> None:
        ...
    
    def add_css_file(self, filename: str, **kwargs: Any) -> None:
        ...
    
    @property
    def script_files(self) -> list[_JavaScript]:
        ...
    
    def init_js_files(self) -> None:
        ...
    
    def add_js_file(self, filename: str, **kwargs: Any) -> None:
        ...
    
    @property
    def math_renderer_name(self) -> str | None:
        ...
    
    def get_outdated_docs(self) -> Iterator[str]:
        ...
    
    def get_asset_paths(self) -> list[str]:
        ...
    
    def render_partial(self, node: Node | None) -> dict[str, str]:
        """Utility: Render a lone doctree node."""
        ...
    
    def prepare_writing(self, docnames: set[str]) -> None:
        ...
    
    def get_doc_context(self, docname: str, body: str, metatags: str) -> dict[str, Any]:
        """Collect items for the template context of a page."""
        ...
    
    def copy_assets(self) -> None:
        ...
    
    def write_doc(self, docname: str, doctree: nodes.document) -> None:
        ...
    
    def write_doc_serialized(self, docname: str, doctree: nodes.document) -> None:
        ...
    
    def finish(self) -> None:
        ...
    
    @progress_message(__('generating indices'))
    def gen_indices(self) -> None:
        ...
    
    def gen_pages_from_extensions(self) -> None:
        ...
    
    @progress_message(__('writing additional pages'))
    def gen_additional_pages(self) -> None:
        ...
    
    def write_genindex(self) -> None:
        ...
    
    def write_domain_indices(self) -> None:
        ...
    
    def copy_image_files(self) -> None:
        ...
    
    def copy_download_files(self) -> None:
        ...
    
    def create_pygments_style_file(self) -> None:
        """create a style file for pygments."""
        ...
    
    def copy_translation_js(self) -> None:
        """Copy a JavaScript file for translations."""
        ...
    
    def copy_stemmer_js(self) -> None:
        """Copy a JavaScript file for stemmer."""
        ...
    
    def copy_theme_static_files(self, context: dict[str, Any]) -> None:
        ...
    
    def copy_html_static_files(self, context: dict) -> None:
        ...
    
    def copy_html_logo(self) -> None:
        ...
    
    def copy_html_favicon(self) -> None:
        ...
    
    def copy_static_files(self) -> None:
        ...
    
    def copy_extra_files(self) -> None:
        """copy html_extra_path files."""
        ...
    
    def write_buildinfo(self) -> None:
        ...
    
    def cleanup(self) -> None:
        ...
    
    def post_process_images(self, doctree: Node) -> None:
        """Pick the best candidate for an image and link down-scaled images to
        their high res version.
        """
        ...
    
    def load_indexer(self, docnames: Iterable[str]) -> None:
        ...
    
    def index_page(self, pagename: str, doctree: nodes.document, title: str) -> None:
        ...
    
    def get_outfilename(self, pagename: str) -> str:
        ...
    
    def add_sidebars(self, pagename: str, ctx: dict) -> None:
        ...
    
    def get_target_uri(self, docname: str, typ: str | None = ...) -> str:
        ...
    
    def handle_page(self, pagename: str, addctx: dict, templatename: str = ..., outfilename: str | None = ..., event_arg: Any = ...) -> None:
        ...
    
    def update_page_context(self, pagename: str, templatename: str, ctx: dict, event_arg: Any) -> None:
        ...
    
    def handle_finish(self) -> None:
        ...
    
    @progress_message(__('dumping object inventory'))
    def dump_inventory(self) -> None:
        ...
    
    def dump_search_index(self) -> None:
        ...
    


def convert_html_css_files(app: Sphinx, config: Config) -> None:
    """This converts string styled html_css_files to tuple styled one."""
    ...

def convert_html_js_files(app: Sphinx, config: Config) -> None:
    """This converts string styled html_js_files to tuple styled one."""
    ...

def setup_resource_paths(app: Sphinx, pagename: str, templatename: str, context: dict, doctree: Node) -> None:
    """Set up relative resource paths."""
    ...

def validate_math_renderer(app: Sphinx) -> None:
    ...

def validate_html_extra_path(app: Sphinx, config: Config) -> None:
    """Check html_extra_paths setting."""
    ...

def validate_html_static_path(app: Sphinx, config: Config) -> None:
    """Check html_static_paths setting."""
    ...

def validate_html_logo(app: Sphinx, config: Config) -> None:
    """Check html_logo setting."""
    ...

def validate_html_favicon(app: Sphinx, config: Config) -> None:
    """Check html_favicon setting."""
    ...

def error_on_html_4(_app: Sphinx, config: Config) -> None:
    """Error on HTML 4."""
    ...

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

_DEPRECATED_OBJECTS = ...
def __getattr__(name): # -> type[_CascadingStyleSheet] | type[_JavaScript]:
    ...

