sphinx_pyppeteer_builder/typings/sphinx/builders/__init__.pyi

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

import codecs
import pickle
import time
from __future__ import annotations
from os import path
from typing import Any, TYPE_CHECKING
from docutils import nodes
from docutils.utils import DependencyList
from sphinx.environment import BuildEnvironment, CONFIG_CHANGED_REASON, CONFIG_OK
from sphinx.environment.adapters.asset import ImageAdapter
from sphinx.errors import SphinxError
from sphinx.locale import __
from sphinx.util import UnicodeDecodeErrorHandler, get_filetype, import_object, logging, rst
from sphinx.util.build_phase import BuildPhase
from sphinx.util.console import bold
from sphinx.util.display import progress_message, status_iterator
from sphinx.util.docutils import sphinx_domains
from sphinx.util.i18n import CatalogInfo, CatalogRepository, docname_to_domain
from sphinx.util.osutil import SEP, ensuredir, relative_uri, relpath
from sphinx.util.parallel import ParallelTasks, SerialTasks, make_chunks, parallel_available
from sphinx import directives, roles
from collections.abc import Iterable, Sequence
from docutils.nodes import Node
from sphinx.application import Sphinx
from sphinx.config import Config
from sphinx.events import EventManager
from sphinx.util.tags import Tags
from sphinx.util.typing import NoneType

"""Builder superclass for all builders."""
if TYPE_CHECKING:
    ...
logger = ...
class Builder:
    """
    Builds target formats from the reST sources.
    """
    name = ...
    format = ...
    epilog = ...
    default_translator_class: type[nodes.NodeVisitor]
    versioning_method = ...
    versioning_compare = ...
    allow_parallel = ...
    use_message_catalog = ...
    supported_image_types: list[str] = ...
    supported_remote_images = ...
    supported_data_uri_images = ...
    def __init__(self, app: Sphinx, env: BuildEnvironment) -> None:
        ...
    
    def get_translator_class(self, *args: Any) -> type[nodes.NodeVisitor]:
        """Return a class of translator."""
        ...
    
    def create_translator(self, *args: Any) -> nodes.NodeVisitor:
        """Return an instance of translator.

        This method returns an instance of ``default_translator_class`` by default.
        Users can replace the translator class with ``app.set_translator()`` API.
        """
        ...
    
    def init(self) -> None:
        """Load necessary templates and perform initialization.  The default
        implementation does nothing.
        """
        ...
    
    def create_template_bridge(self) -> None:
        """Return the template bridge configured."""
        ...
    
    def get_target_uri(self, docname: str, typ: str | None = ...) -> str:
        """Return the target URI for a document name.

        *typ* can be used to qualify the link characteristic for individual
        builders.
        """
        ...
    
    def get_relative_uri(self, from_: str, to: str, typ: str | None = ...) -> str:
        """Return a relative URI between two source filenames.

        May raise environment.NoUri if there's no way to return a sensible URI.
        """
        ...
    
    def get_outdated_docs(self) -> str | Iterable[str]:
        """Return an iterable of output files that are outdated, or a string
        describing what an update build will build.

        If the builder does not output individual files corresponding to
        source files, return a string here.  If it does, return an iterable
        of those files that need to be written.
        """
        ...
    
    def get_asset_paths(self) -> list[str]:
        """Return list of paths for assets (ex. templates, CSS, etc.)."""
        ...
    
    def post_process_images(self, doctree: Node) -> None:
        """Pick the best candidate for all image URIs."""
        ...
    
    def compile_catalogs(self, catalogs: set[CatalogInfo], message: str) -> None:
        ...
    
    def compile_all_catalogs(self) -> None:
        ...
    
    def compile_specific_catalogs(self, specified_files: list[str]) -> None:
        ...
    
    def compile_update_catalogs(self) -> None:
        ...
    
    def build_all(self) -> None:
        """Build all source files."""
        ...
    
    def build_specific(self, filenames: list[str]) -> None:
        """Only rebuild as much as needed for changes in the *filenames*."""
        ...
    
    def build_update(self) -> None:
        """Only rebuild what was changed or added since last build."""
        ...
    
    def build(self, docnames: Iterable[str] | None, summary: str | None = ..., method: str = ...) -> None:
        """Main build method.

        First updates the environment, and then calls
        :meth:`!write`.
        """
        ...
    
    def read(self) -> list[str]:
        """(Re-)read all files new or changed since last update.

        Store all environment docnames in the canonical format (ie using SEP as
        a separator in place of os.path.sep).
        """
        ...
    
    def read_doc(self, docname: str, *, _cache: bool = ...) -> None:
        """Parse a file and add/update inventory entries for the doctree."""
        ...
    
    def write_doctree(self, docname: str, doctree: nodes.document, *, _cache: bool = ...) -> None:
        """Write the doctree to a file."""
        ...
    
    def write(self, build_docnames: Iterable[str] | None, updated_docnames: Sequence[str], method: str = ...) -> None:
        ...
    
    def prepare_writing(self, docnames: set[str]) -> None:
        """A place where you can add logic before :meth:`write_doc` is run"""
        ...
    
    def copy_assets(self) -> None:
        """Where assets (images, static files, etc) are copied before writing"""
        ...
    
    def write_doc(self, docname: str, doctree: nodes.document) -> None:
        """Where you actually write something to the filesystem."""
        ...
    
    def write_doc_serialized(self, docname: str, doctree: nodes.document) -> None:
        """Handle parts of write_doc that must be called in the main process
        if parallel build is active.
        """
        ...
    
    def finish(self) -> None:
        """Finish the building process.

        The default implementation does nothing.
        """
        ...
    
    def cleanup(self) -> None:
        """Cleanup any resources.

        The default implementation does nothing.
        """
        ...
    
    def get_builder_config(self, option: str, default: str) -> Any:
        """Return a builder specific option.

        This method allows customization of common builder settings by
        inserting the name of the current builder in the option key.
        If the key does not exist, use default as builder name.
        """
        ...