sphinx.domains.Domain

class documentation

class Domain:

Known subclasses: sphinx.domains.python.PythonDomain, sphinx.domains.c.CDomain, sphinx.domains.changeset.ChangeSetDomain, sphinx.domains.citation.CitationDomain, sphinx.domains.cpp.CPPDomain, sphinx.domains.index.IndexDomain, sphinx.domains.javascript.JavaScriptDomain, sphinx.domains.math.MathDomain, sphinx.domains.rst.ReSTDomain, sphinx.domains.std.StandardDomain, sphinx.ext.duration.DurationDomain, sphinx.ext.todo.TodoDomain

View In Hierarchy

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' data_version attribute. Otherwise, OSError is raised and the pickled environment is discarded.

Method	`add_object_type`	Add an object type.
Method	`check_consistency`	Do consistency checks (experimental).
Method	`clear_doc`	Remove traces of a document in the domain-specific inventories.
Method	`directive`	Return a directive adapter class that always gives the registered directive its full name ('domain:name') as `self.name`.
Method	`get_enumerable_node_type`	Get type of enumerable nodes (experimental).
Method	`get_full_qualified_name`	Return full qualified name for given node.
Method	`get_objects`	Return an iterable of "object descriptions".
Method	`get_type_name`	Return full name for given ObjType.
Method	`merge_domaindata`	Merge in data regarding docnames from a different domaindata inventory (coming from a subprocess in parallel builds).
Method	`process_doc`	Process a document after it is read by the environment.
Method	`process_field_xref`	Process a pending xref created in a doc field. For example, attach information about the current scope.
Method	`resolve_any_xref`	Resolve the pending_xref node with the given target.
Method	`resolve_xref`	Resolve the pending_xref node with the given typ and target.
Method	`role`	Return a role adapter function that always gives the registered role its full name ('domain:name') as the first argument.
Method	`setup`	Set up domain object.
Class Variable	`dangling_warnings`	Undocumented
Class Variable	`data_version`	Undocumented
Class Variable	`enumerable_nodes`	Undocumented
Class Variable	`initial_data`	Undocumented
Class Variable	`label`	Undocumented
Class Variable	`name`	Undocumented
Instance Variable	`data`	Undocumented
Instance Variable	`directives`	Undocumented
Instance Variable	`indices`	Undocumented
Instance Variable	`object_types`	Undocumented
Instance Variable	`roles`	Undocumented
Method	`__init__`	Undocumented
Instance Variable	`_directive_cache`	Undocumented
Instance Variable	`_role2type`	Undocumented
Instance Variable	`_role_cache`	Undocumented
Instance Variable	`_type2role`	Undocumented
Instance Variable	`env`	Undocumented
Instance Variable	`objtypes_for_role`	Undocumented
Instance Variable	`role_for_objtype`	Undocumented

def add_object_type(self, name, objtype):

Add an object type.

Parameters
name:`str`	Undocumented
objtype:`ObjType`	Undocumented

def check_consistency(self):

overridden in sphinx.domains.citation.CitationDomain

Do consistency checks (experimental).

def clear_doc(self, docname):

overridden in sphinx.domains.python.PythonDomain, sphinx.domains.c.CDomain, sphinx.domains.changeset.ChangeSetDomain, sphinx.domains.citation.CitationDomain, sphinx.domains.cpp.CPPDomain, sphinx.domains.index.IndexDomain, sphinx.domains.javascript.JavaScriptDomain, sphinx.domains.math.MathDomain, sphinx.domains.rst.ReSTDomain, sphinx.domains.std.StandardDomain, sphinx.ext.duration.DurationDomain, sphinx.ext.todo.TodoDomain

Remove traces of a document in the domain-specific inventories.

Parameters
docname:`str`	Undocumented

def directive(self, name):

Return a directive adapter class that always gives the registered directive its full name ('domain:name') as self.name.

Parameters
name:`str`	Undocumented
Returns
`Optional[Callable]`	Undocumented

def get_enumerable_node_type(self, node):

overridden in sphinx.domains.std.StandardDomain

Get type of enumerable nodes (experimental).

Parameters
node:`Node`	Undocumented
Returns
`Optional[str]`	Undocumented

def get_full_qualified_name(self, node):

overridden in sphinx.domains.python.PythonDomain, sphinx.domains.cpp.CPPDomain, sphinx.domains.javascript.JavaScriptDomain, sphinx.domains.std.StandardDomain

Return full qualified name for given node.

Parameters
node:`Element`	Undocumented
Returns
`Optional[str]`	Undocumented

def get_objects(self):

overridden in sphinx.domains.python.PythonDomain, sphinx.domains.c.CDomain, sphinx.domains.cpp.CPPDomain, sphinx.domains.javascript.JavaScriptDomain, sphinx.domains.math.MathDomain, sphinx.domains.rst.ReSTDomain, sphinx.domains.std.StandardDomain

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.

Returns
`Iterable[Tuple[str, str, str, str, str, int]]`	Undocumented

def get_type_name(self, type, primary=False):

overridden in sphinx.domains.std.StandardDomain

Return full name for given ObjType.

Parameters
type:`ObjType`	Undocumented
primary:`bool`	Undocumented
Returns
`str`	Undocumented

def merge_domaindata(self, docnames, otherdata):

Merge in data regarding docnames from a different domaindata inventory (coming from a subprocess in parallel builds).

Parameters
docnames:`List[str]`	Undocumented
otherdata:`Dict`	Undocumented

def process_doc(self, env, docname, document):

overridden in sphinx.domains.c.CDomain, sphinx.domains.changeset.ChangeSetDomain, sphinx.domains.cpp.CPPDomain, sphinx.domains.index.IndexDomain, sphinx.domains.math.MathDomain, sphinx.domains.std.StandardDomain, sphinx.ext.todo.TodoDomain

Process a document after it is read by the environment.

Parameters
env:`BuildEnvironment`	Undocumented
docname:`str`	Undocumented
document:`nodes.document`	Undocumented

def process_field_xref(self, pnode):

overridden in sphinx.domains.c.CDomain, sphinx.domains.cpp.CPPDomain

Process a pending xref created in a doc field. For example, attach information about the current scope.

Parameters
pnode:`pending_xref`	Undocumented

def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode):

overridden in sphinx.domains.python.PythonDomain, sphinx.domains.c.CDomain, sphinx.domains.citation.CitationDomain, sphinx.domains.cpp.CPPDomain, sphinx.domains.javascript.JavaScriptDomain, sphinx.domains.math.MathDomain, sphinx.domains.rst.ReSTDomain, sphinx.domains.std.StandardDomain

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 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 resolve_xref would return.

New in version 1.3.

Parameters
env:`BuildEnvironment`	Undocumented
fromdocname:`str`	Undocumented
builder:`Builder`	Undocumented
target:`str`	Undocumented
node:`pending_xref`	Undocumented
contnode:`Element`	Undocumented
Returns
`List[Tuple[str, Element]]`	Undocumented

def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):

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 sphinx.environment.NoUri to suppress the :event:`missing-reference` event being emitted.

Parameters
env:`BuildEnvironment`	Undocumented
fromdocname:`str`	Undocumented
builder:`Builder`	Undocumented
typ:`str`	Undocumented
target:`str`	Undocumented
node:`pending_xref`	Undocumented
contnode:`Element`	Undocumented
Returns
`Optional[Element]`	Undocumented

def role(self, name):

Return a role adapter function that always gives the registered role its full name ('domain:name') as the first argument.

Parameters
name:`str`	Undocumented
Returns
`Optional[RoleFunction]`	Undocumented

def setup(self):

Set up domain object.

dangling_warnings: Dict[str, str] =

overridden in sphinx.domains.citation.CitationDomain, sphinx.domains.math.MathDomain, sphinx.domains.std.StandardDomain

Undocumented

data_version: int =

Undocumented

enumerable_nodes: Dict[Type[Node], Tuple[str, Callable]] =

overridden in sphinx.domains.math.MathDomain, sphinx.domains.std.StandardDomain

Undocumented

initial_data: Dict =

overridden in sphinx.domains.python.PythonDomain, sphinx.domains.c.CDomain, sphinx.domains.changeset.ChangeSetDomain, sphinx.domains.cpp.CPPDomain, sphinx.domains.javascript.JavaScriptDomain, sphinx.domains.math.MathDomain, sphinx.domains.rst.ReSTDomain, sphinx.domains.std.StandardDomain

Undocumented

label: str =

Undocumented

name: str =

Undocumented

data =

Undocumented

directives =

overridden in sphinx.domains.python.PythonDomain, sphinx.domains.c.CDomain, sphinx.domains.cpp.CPPDomain, sphinx.domains.javascript.JavaScriptDomain, sphinx.domains.rst.ReSTDomain, sphinx.domains.std.StandardDomain

Undocumented

indices =

overridden in sphinx.domains.python.PythonDomain

Undocumented

object_types =

overridden in sphinx.domains.python.PythonDomain, sphinx.domains.c.CDomain, sphinx.domains.cpp.CPPDomain, sphinx.domains.javascript.JavaScriptDomain, sphinx.domains.rst.ReSTDomain, sphinx.domains.std.StandardDomain

Undocumented

roles =

Undocumented

def __init__(self, env):

overridden in sphinx.domains.std.StandardDomain

Undocumented

Parameters
env:`BuildEnvironment`	Undocumented

_directive_cache: Dict[str, Callable] =

Undocumented

_role2type: Dict[str, List[str]] =

Undocumented

_role_cache: Dict[str, Callable] =

Undocumented

_type2role: Dict[str, str] =

Undocumented

env: BuildEnvironment =

Undocumented

objtypes_for_role: Callable[[str], List[str]] =

Undocumented

role_for_objtype: Callable[[str], str] =

Undocumented