308 lines
11 KiB
Python
308 lines
11 KiB
Python
"""
|
|
This type stub file was generated by pyright.
|
|
"""
|
|
|
|
import copy
|
|
from __future__ import annotations
|
|
from abc import ABC, abstractmethod
|
|
from typing import Any, Callable, NamedTuple, Optional, TYPE_CHECKING, cast
|
|
from docutils.nodes import Element, Node, system_message
|
|
from sphinx.errors import SphinxError
|
|
from sphinx.locale import _
|
|
from collections.abc import Iterable, Sequence
|
|
from docutils import nodes
|
|
from docutils.parsers.rst import Directive
|
|
from docutils.parsers.rst.states import Inliner
|
|
from sphinx.addnodes import pending_xref
|
|
from sphinx.builders import Builder
|
|
from sphinx.environment import BuildEnvironment
|
|
from sphinx.roles import XRefRole
|
|
from sphinx.util.typing import RoleFunction
|
|
|
|
"""Support for domains.
|
|
|
|
Domains are groupings of description directives
|
|
and roles describing e.g. constructs of one programming language.
|
|
"""
|
|
if TYPE_CHECKING:
|
|
...
|
|
class ObjType:
|
|
"""
|
|
An ObjType is the description for a type of object that a domain can
|
|
document. In the object_types attribute of Domain subclasses, object type
|
|
names are mapped to instances of this class.
|
|
|
|
Constructor arguments:
|
|
|
|
- *lname*: localized name of the type (do not include domain name)
|
|
- *roles*: all the roles that can refer to an object of this type
|
|
- *attrs*: object attributes -- currently only "searchprio" is known,
|
|
which defines the object's priority in the full-text search index,
|
|
see :meth:`Domain.get_objects()`.
|
|
"""
|
|
known_attrs = ...
|
|
def __init__(self, lname: str, *roles: Any, **attrs: Any) -> None:
|
|
...
|
|
|
|
|
|
|
|
class IndexEntry(NamedTuple):
|
|
name: str
|
|
subtype: int
|
|
docname: str
|
|
anchor: str
|
|
extra: str
|
|
qualifier: str
|
|
descr: str
|
|
...
|
|
|
|
|
|
class Index(ABC):
|
|
"""
|
|
An Index is the description for a domain-specific index. To add an index to
|
|
a domain, subclass Index, overriding the three name attributes:
|
|
|
|
* `name` is an identifier used for generating file names.
|
|
It is also used for a hyperlink target for the index. Therefore, users can
|
|
refer the index page using ``ref`` role and a string which is combined
|
|
domain name and ``name`` attribute (ex. ``:ref:`py-modindex```).
|
|
* `localname` is the section title for the index.
|
|
* `shortname` is a short name for the index, for use in the relation bar in
|
|
HTML output. Can be empty to disable entries in the relation bar.
|
|
|
|
and providing a :meth:`generate()` method. Then, add the index class to
|
|
your domain's `indices` list. Extensions can add indices to existing
|
|
domains using :meth:`~sphinx.application.Sphinx.add_index_to_domain()`.
|
|
|
|
.. versionchanged:: 3.0
|
|
|
|
Index pages can be referred by domain name and index name via
|
|
:rst:role:`ref` role.
|
|
"""
|
|
name: str
|
|
localname: str
|
|
shortname: str | None = ...
|
|
def __init__(self, domain: Domain) -> None:
|
|
...
|
|
|
|
@abstractmethod
|
|
def generate(self, docnames: Iterable[str] | None = ...) -> tuple[list[tuple[str, list[IndexEntry]]], bool]:
|
|
"""Get entries for the index.
|
|
|
|
If ``docnames`` is given, restrict to entries referring to these
|
|
docnames.
|
|
|
|
The return value is a tuple of ``(content, collapse)``:
|
|
|
|
``collapse``
|
|
A boolean that determines if sub-entries should start collapsed (for
|
|
output formats that support collapsing sub-entries).
|
|
|
|
``content``:
|
|
A sequence of ``(letter, entries)`` tuples, where ``letter`` is the
|
|
"heading" for the given ``entries``, usually the starting letter, and
|
|
``entries`` is a sequence of single entries. Each entry is a sequence
|
|
``[name, subtype, docname, anchor, extra, qualifier, descr]``. The
|
|
items in this sequence have the following meaning:
|
|
|
|
``name``
|
|
The name of the index entry to be displayed.
|
|
|
|
``subtype``
|
|
The sub-entry related type. One of:
|
|
|
|
``0``
|
|
A normal entry.
|
|
``1``
|
|
An entry with sub-entries.
|
|
``2``
|
|
A sub-entry.
|
|
|
|
``docname``
|
|
*docname* where the entry is located.
|
|
|
|
``anchor``
|
|
Anchor for the entry within ``docname``
|
|
|
|
``extra``
|
|
Extra info for the entry.
|
|
|
|
``qualifier``
|
|
Qualifier for the description.
|
|
|
|
``descr``
|
|
Description for the entry.
|
|
|
|
Qualifier and description are not rendered for some output formats such
|
|
as LaTeX.
|
|
"""
|
|
...
|
|
|
|
|
|
|
|
TitleGetter = Callable[[Node], Optional[str]]
|
|
class Domain:
|
|
"""
|
|
A Domain is meant to be a group of "object" description directives for
|
|
objects of a similar nature, and corresponding roles to create references to
|
|
them. Examples would be Python modules, classes, functions etc., elements
|
|
of a templating language, Sphinx roles and directives, etc.
|
|
|
|
Each domain has a separate storage for information about existing objects
|
|
and how to reference them in `self.data`, which must be a dictionary. It
|
|
also must implement several functions that expose the object information in
|
|
a uniform way to parts of Sphinx that allow the user to reference or search
|
|
for objects in a domain-agnostic way.
|
|
|
|
About `self.data`: since all object and cross-referencing information is
|
|
stored on a BuildEnvironment instance, the `domain.data` object is also
|
|
stored in the `env.domaindata` dict under the key `domain.name`. Before the
|
|
build process starts, every active domain is instantiated and given the
|
|
environment object; the `domaindata` dict must then either be nonexistent or
|
|
a dictionary whose 'version' key is equal to the domain class'
|
|
:attr:`data_version` attribute. Otherwise, `OSError` is raised and the
|
|
pickled environment is discarded.
|
|
"""
|
|
name = ...
|
|
label = ...
|
|
object_types: dict[str, ObjType] = ...
|
|
directives: dict[str, type[Directive]] = ...
|
|
roles: dict[str, RoleFunction | XRefRole] = ...
|
|
indices: list[type[Index]] = ...
|
|
dangling_warnings: dict[str, str] = ...
|
|
enumerable_nodes: dict[type[Node], tuple[str, TitleGetter | None]] = ...
|
|
initial_data: dict = ...
|
|
data: dict
|
|
data_version = ...
|
|
def __init__(self, env: BuildEnvironment) -> None:
|
|
...
|
|
|
|
def setup(self) -> None:
|
|
"""Set up domain object."""
|
|
...
|
|
|
|
def add_object_type(self, name: str, objtype: ObjType) -> None:
|
|
"""Add an object type."""
|
|
...
|
|
|
|
def role(self, name: str) -> RoleFunction | None:
|
|
"""Return a role adapter function that always gives the registered
|
|
role its full name ('domain:name') as the first argument.
|
|
"""
|
|
...
|
|
|
|
def directive(self, name: str) -> Callable | None:
|
|
"""Return a directive adapter class that always gives the registered
|
|
directive its full name ('domain:name') as ``self.name``.
|
|
"""
|
|
class DirectiveAdapter(BaseDirective):
|
|
...
|
|
|
|
|
|
|
|
def clear_doc(self, docname: str) -> None:
|
|
"""Remove traces of a document in the domain-specific inventories."""
|
|
...
|
|
|
|
def merge_domaindata(self, docnames: list[str], otherdata: dict) -> None:
|
|
"""Merge in data regarding *docnames* from a different domaindata
|
|
inventory (coming from a subprocess in parallel builds).
|
|
"""
|
|
...
|
|
|
|
def process_doc(self, env: BuildEnvironment, docname: str, document: nodes.document) -> None:
|
|
"""Process a document after it is read by the environment."""
|
|
...
|
|
|
|
def check_consistency(self) -> None:
|
|
"""Do consistency checks (**experimental**)."""
|
|
...
|
|
|
|
def process_field_xref(self, pnode: pending_xref) -> None:
|
|
"""Process a pending xref created in a doc field.
|
|
For example, attach information about the current scope.
|
|
"""
|
|
...
|
|
|
|
def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder, typ: str, target: str, node: pending_xref, contnode: Element) -> Element | None:
|
|
"""Resolve the pending_xref *node* with the given *typ* and *target*.
|
|
|
|
This method should return a new node, to replace the xref node,
|
|
containing the *contnode* which is the markup content of the
|
|
cross-reference.
|
|
|
|
If no resolution can be found, None can be returned; the xref node will
|
|
then given to the :event:`missing-reference` event, and if that yields no
|
|
resolution, replaced by *contnode*.
|
|
|
|
The method can also raise :exc:`sphinx.environment.NoUri` to suppress
|
|
the :event:`missing-reference` event being emitted.
|
|
"""
|
|
...
|
|
|
|
def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder, target: str, node: pending_xref, contnode: Element) -> list[tuple[str, Element]]:
|
|
"""Resolve the pending_xref *node* with the given *target*.
|
|
|
|
The reference comes from an "any" or similar role, which means that we
|
|
don't know the type. Otherwise, the arguments are the same as for
|
|
:meth:`resolve_xref`.
|
|
|
|
The method must return a list (potentially empty) of tuples
|
|
``('domain:role', newnode)``, where ``'domain:role'`` is the name of a
|
|
role that could have created the same reference, e.g. ``'py:func'``.
|
|
``newnode`` is what :meth:`resolve_xref` would return.
|
|
|
|
.. versionadded:: 1.3
|
|
"""
|
|
...
|
|
|
|
def get_objects(self) -> Iterable[tuple[str, str, str, str, str, int]]:
|
|
"""Return an iterable of "object descriptions".
|
|
|
|
Object descriptions are tuples with six items:
|
|
|
|
``name``
|
|
Fully qualified name.
|
|
|
|
``dispname``
|
|
Name to display when searching/linking.
|
|
|
|
``type``
|
|
Object type, a key in ``self.object_types``.
|
|
|
|
``docname``
|
|
The document where it is to be found.
|
|
|
|
``anchor``
|
|
The anchor name for the object.
|
|
|
|
``priority``
|
|
How "important" the object is (determines placement in search
|
|
results). One of:
|
|
|
|
``1``
|
|
Default priority (placed before full-text matches).
|
|
``0``
|
|
Object is important (placed before default-priority objects).
|
|
``2``
|
|
Object is unimportant (placed after full-text matches).
|
|
``-1``
|
|
Object should not show up in search at all.
|
|
"""
|
|
...
|
|
|
|
def get_type_name(self, type: ObjType, primary: bool = ...) -> str:
|
|
"""Return full name for given ObjType."""
|
|
...
|
|
|
|
def get_enumerable_node_type(self, node: Node) -> str | None:
|
|
"""Get type of enumerable nodes (experimental)."""
|
|
...
|
|
|
|
def get_full_qualified_name(self, node: Element) -> str | None:
|
|
"""Return full qualified name for given node."""
|
|
...
|
|
|
|
|
|
|