311 lines
9.9 KiB
Python
311 lines
9.9 KiB
Python
"""
|
|
This type stub file was generated by pyright.
|
|
"""
|
|
|
|
import functools
|
|
import os
|
|
import pickle
|
|
import time
|
|
from __future__ import annotations
|
|
from collections import defaultdict
|
|
from copy import copy
|
|
from os import path
|
|
from typing import Any, Callable, Literal, TYPE_CHECKING
|
|
from sphinx import addnodes
|
|
from sphinx.environment.adapters import toctree as toctree_adapters
|
|
from sphinx.errors import BuildEnvironmentError, DocumentError, ExtensionError, SphinxError
|
|
from sphinx.locale import __
|
|
from sphinx.transforms import SphinxTransformer
|
|
from sphinx.util import DownloadFiles, FilenameUniqDict, logging
|
|
from sphinx.util.docutils import LoggingReporter
|
|
from sphinx.util.i18n import CatalogRepository, docname_to_domain
|
|
from sphinx.util.nodes import is_translatable
|
|
from sphinx.util.osutil import canon_path, os_path
|
|
from collections.abc import Generator, Iterator, MutableMapping
|
|
from pathlib import Path
|
|
from docutils import nodes
|
|
from docutils.nodes import Node
|
|
from sphinx.application import Sphinx
|
|
from sphinx.builders import Builder
|
|
from sphinx.config import Config
|
|
from sphinx.domains import Domain
|
|
from sphinx.events import EventManager
|
|
from sphinx.project import Project
|
|
from typing_extensions import overload
|
|
from sphinx.domains.c import CDomain
|
|
from sphinx.domains.changeset import ChangeSetDomain
|
|
from sphinx.domains.citation import CitationDomain
|
|
from sphinx.domains.cpp import CPPDomain
|
|
from sphinx.domains.index import IndexDomain
|
|
from sphinx.domains.javascript import JavaScriptDomain
|
|
from sphinx.domains.math import MathDomain
|
|
from sphinx.domains.python import PythonDomain
|
|
from sphinx.domains.rst import ReSTDomain
|
|
from sphinx.domains.std import StandardDomain
|
|
from sphinx.ext.duration import DurationDomain
|
|
from sphinx.ext.todo import TodoDomain
|
|
|
|
"""Global creation environment."""
|
|
if TYPE_CHECKING:
|
|
...
|
|
logger = ...
|
|
default_settings: dict[str, Any] = ...
|
|
ENV_VERSION = ...
|
|
CONFIG_UNSET = ...
|
|
CONFIG_OK = ...
|
|
CONFIG_NEW = ...
|
|
CONFIG_CHANGED = ...
|
|
CONFIG_EXTENSIONS_CHANGED = ...
|
|
CONFIG_CHANGED_REASON = ...
|
|
versioning_conditions: dict[str, bool | Callable] = ...
|
|
if TYPE_CHECKING:
|
|
class _DomainsType(MutableMapping[str, Domain]):
|
|
@overload
|
|
def __getitem__(self, key: Literal["c"]) -> CDomain:
|
|
...
|
|
|
|
@overload
|
|
def __getitem__(self, key: Literal["cpp"]) -> CPPDomain:
|
|
...
|
|
|
|
@overload
|
|
def __getitem__(self, key: Literal["changeset"]) -> ChangeSetDomain:
|
|
...
|
|
|
|
@overload
|
|
def __getitem__(self, key: Literal["citation"]) -> CitationDomain:
|
|
...
|
|
|
|
@overload
|
|
def __getitem__(self, key: Literal["index"]) -> IndexDomain:
|
|
...
|
|
|
|
@overload
|
|
def __getitem__(self, key: Literal["js"]) -> JavaScriptDomain:
|
|
...
|
|
|
|
@overload
|
|
def __getitem__(self, key: Literal["math"]) -> MathDomain:
|
|
...
|
|
|
|
@overload
|
|
def __getitem__(self, key: Literal["py"]) -> PythonDomain:
|
|
...
|
|
|
|
@overload
|
|
def __getitem__(self, key: Literal["rst"]) -> ReSTDomain:
|
|
...
|
|
|
|
@overload
|
|
def __getitem__(self, key: Literal["std"]) -> StandardDomain:
|
|
...
|
|
|
|
@overload
|
|
def __getitem__(self, key: Literal["duration"]) -> DurationDomain:
|
|
...
|
|
|
|
@overload
|
|
def __getitem__(self, key: Literal["todo"]) -> TodoDomain:
|
|
...
|
|
|
|
@overload
|
|
def __getitem__(self, key: str) -> Domain:
|
|
...
|
|
|
|
def __getitem__(self, key):
|
|
...
|
|
|
|
def __setitem__(self, key, value):
|
|
...
|
|
|
|
def __delitem__(self, key):
|
|
...
|
|
|
|
def __iter__(self):
|
|
...
|
|
|
|
def __len__(self):
|
|
...
|
|
|
|
|
|
|
|
else:
|
|
...
|
|
class BuildEnvironment:
|
|
"""
|
|
The environment in which the ReST files are translated.
|
|
Stores an inventory of cross-file targets and provides doctree
|
|
transformations to resolve links to them.
|
|
"""
|
|
domains: _DomainsType
|
|
def __init__(self, app: Sphinx) -> None:
|
|
...
|
|
|
|
def __getstate__(self) -> dict:
|
|
"""Obtains serializable data for pickling."""
|
|
...
|
|
|
|
def __setstate__(self, state: dict) -> None:
|
|
...
|
|
|
|
def setup(self, app: Sphinx) -> None:
|
|
"""Set up BuildEnvironment object."""
|
|
...
|
|
|
|
def set_versioning_method(self, method: str | Callable, compare: bool) -> None:
|
|
"""This sets the doctree versioning method for this environment.
|
|
|
|
Versioning methods are a builder property; only builders with the same
|
|
versioning method can share the same doctree directory. Therefore, we
|
|
raise an exception if the user tries to use an environment with an
|
|
incompatible versioning method.
|
|
"""
|
|
...
|
|
|
|
def clear_doc(self, docname: str) -> None:
|
|
"""Remove all traces of a source file in the inventory."""
|
|
...
|
|
|
|
def merge_info_from(self, docnames: list[str], other: BuildEnvironment, app: Sphinx) -> None:
|
|
"""Merge global information gathered about *docnames* while reading them
|
|
from the *other* environment.
|
|
|
|
This possibly comes from a parallel build process.
|
|
"""
|
|
...
|
|
|
|
def path2doc(self, filename: str | os.PathLike[str]) -> str | None:
|
|
"""Return the docname for the filename if the file is document.
|
|
|
|
*filename* should be absolute or relative to the source directory.
|
|
"""
|
|
...
|
|
|
|
def doc2path(self, docname: str, base: bool = ...) -> str:
|
|
"""Return the filename for the document name.
|
|
|
|
If *base* is True, return absolute path under self.srcdir.
|
|
If *base* is False, return relative path to self.srcdir.
|
|
"""
|
|
...
|
|
|
|
def relfn2path(self, filename: str, docname: str | None = ...) -> tuple[str, str]:
|
|
"""Return paths to a file referenced from a document, relative to
|
|
documentation root and absolute.
|
|
|
|
In the input "filename", absolute filenames are taken as relative to the
|
|
source dir, while relative filenames are relative to the dir of the
|
|
containing document.
|
|
"""
|
|
...
|
|
|
|
@property
|
|
def found_docs(self) -> set[str]:
|
|
"""contains all existing docnames."""
|
|
...
|
|
|
|
def find_files(self, config: Config, builder: Builder) -> None:
|
|
"""Find all source files in the source dir and put them in
|
|
self.found_docs.
|
|
"""
|
|
...
|
|
|
|
def get_outdated_files(self, config_changed: bool) -> tuple[set[str], set[str], set[str]]:
|
|
"""Return (added, changed, removed) sets."""
|
|
...
|
|
|
|
def check_dependents(self, app: Sphinx, already: set[str]) -> Generator[str, None, None]:
|
|
...
|
|
|
|
def prepare_settings(self, docname: str) -> None:
|
|
"""Prepare to set up environment for reading."""
|
|
...
|
|
|
|
@property
|
|
def docname(self) -> str:
|
|
"""Returns the docname of the document currently being parsed."""
|
|
...
|
|
|
|
def new_serialno(self, category: str = ...) -> int:
|
|
"""Return a serial number, e.g. for index entry targets.
|
|
|
|
The number is guaranteed to be unique in the current document.
|
|
"""
|
|
...
|
|
|
|
def note_dependency(self, filename: str) -> None:
|
|
"""Add *filename* as a dependency of the current document.
|
|
|
|
This means that the document will be rebuilt if this file changes.
|
|
|
|
*filename* should be absolute or relative to the source directory.
|
|
"""
|
|
...
|
|
|
|
def note_included(self, filename: str) -> None:
|
|
"""Add *filename* as a included from other document.
|
|
|
|
This means the document is not orphaned.
|
|
|
|
*filename* should be absolute or relative to the source directory.
|
|
"""
|
|
...
|
|
|
|
def note_reread(self) -> None:
|
|
"""Add the current document to the list of documents that will
|
|
automatically be re-read at the next build.
|
|
"""
|
|
...
|
|
|
|
def get_domain(self, domainname: str) -> Domain:
|
|
"""Return the domain instance with the specified name.
|
|
|
|
Raises an ExtensionError if the domain is not registered.
|
|
"""
|
|
...
|
|
|
|
def get_doctree(self, docname: str) -> nodes.document:
|
|
"""Read the doctree for a file from the pickle and return it."""
|
|
...
|
|
|
|
@functools.cached_property
|
|
def master_doctree(self) -> nodes.document:
|
|
...
|
|
|
|
def get_and_resolve_doctree(self, docname: str, builder: Builder, doctree: nodes.document | None = ..., prune_toctrees: bool = ..., includehidden: bool = ...) -> nodes.document:
|
|
"""Read the doctree from the pickle, resolve cross-references and
|
|
toctrees and return it.
|
|
"""
|
|
...
|
|
|
|
def resolve_toctree(self, docname: str, builder: Builder, toctree: addnodes.toctree, prune: bool = ..., maxdepth: int = ..., titles_only: bool = ..., collapse: bool = ..., includehidden: bool = ...) -> Node | None:
|
|
"""Resolve a *toctree* node into individual bullet lists with titles
|
|
as items, returning None (if no containing titles are found) or
|
|
a new node.
|
|
|
|
If *prune* is True, the tree is pruned to *maxdepth*, or if that is 0,
|
|
to the value of the *maxdepth* option on the *toctree* node.
|
|
If *titles_only* is True, only toplevel document titles will be in the
|
|
resulting tree.
|
|
If *collapse* is True, all branches not containing docname will
|
|
be collapsed.
|
|
"""
|
|
...
|
|
|
|
def resolve_references(self, doctree: nodes.document, fromdocname: str, builder: Builder) -> None:
|
|
...
|
|
|
|
def apply_post_transforms(self, doctree: nodes.document, docname: str) -> None:
|
|
"""Apply all post-transforms."""
|
|
...
|
|
|
|
def collect_relations(self) -> dict[str, list[str | None]]:
|
|
...
|
|
|
|
def check_consistency(self) -> None:
|
|
"""Do consistency checks."""
|
|
...
|
|
|
|
|
|
|