Domain API

Domain API

class sphinx.domains.Domain(env: BuildEnvironment)[source]

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.

add_object_type(name: str, objtype: sphinx.domains.ObjType) → None[source]

Add an object type.

check_consistency() → None[source]

Do consistency checks (experimental).

clear_doc(docname: str) → None[source]

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

directive(name: str) → Optional[Callable][source]

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

get_enumerable_node_type(node: docutils.nodes.Node) → Optional[str][source]

Get type of enumerable nodes (experimental).

get_full_qualified_name(node: docutils.nodes.Element) → Optional[str][source]

Return full qualified name for given node.

get_objects() → Iterable[Tuple[str, str, str, str, str, int]][source]

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.

get_type_name(type: sphinx.domains.ObjType, primary: bool = False) → str[source]

Return full name for given ObjType.

merge_domaindata(docnames: List[str], otherdata: Dict) → None[source]

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

process_doc(env: BuildEnvironment, docname: str, document: docutils.nodes.document) → None[source]

Process a document after it is read by the environment.

process_field_xref(pnode: sphinx.addnodes.pending_xref) → None[source]

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

resolve_any_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, target: str, node: sphinx.addnodes.pending_xref, contnode: docutils.nodes.Element) → List[Tuple[str, docutils.nodes.Element]][source]

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.

resolve_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, typ: str, target: str, node: sphinx.addnodes.pending_xref, contnode: docutils.nodes.Element) → Optional[docutils.nodes.Element][source]

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 missing-reference event, and if that yields no resolution, replaced by contnode.

The method can also raise sphinx.environment.NoUri to suppress the missing-reference event being emitted.

role(name: str) → Optional[Callable[[str, str, str, int, docutils.parsers.rst.states.Inliner, Dict[str, Any], List[str]], Tuple[List[docutils.nodes.Node], List[docutils.nodes.system_message]]]][source]

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

setup() → None[source]

Set up domain object.

dangling_warnings: Dict[str, str] = {}

role name -> a warning message if reference is missing

data: Dict

data value

data_version = 0

data version, bump this when the format of self.data changes

directives: Dict[str, Any] = {}

directive name -> directive class

enumerable_nodes: Dict[Type[docutils.nodes.Node], Tuple[str, Callable]] = {}

node_class -> (enum_node_type, title_getter)

indices: List[Type[sphinx.domains.Index]] = []

a list of Index subclasses

initial_data: Dict = {}

data value for a fresh environment

label =

domain label: longer, more descriptive (used in messages)

name =

domain name: should be short, but unique

object_types: Dict[str, sphinx.domains.ObjType] = {}

type (usually directive) name -> ObjType instance

roles: Dict[str, Union[Callable[[str, str, str, int, docutils.parsers.rst.states.Inliner, Dict[str, Any], List[str]], Tuple[List[docutils.nodes.Node], List[docutils.nodes.system_message]]], sphinx.roles.XRefRole]] = {}

role name -> role callable

class sphinx.domains.ObjType(lname: str, *roles: Any, **attrs: Any)[source]

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 Domain.get_objects().

class sphinx.domains.Index(domain: sphinx.domains.Domain)[source]

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 generate() method. Then, add the index class to your domain’s indices list. Extensions can add indices to existing domains using add_index_to_domain().

Changed in version 3.0: Index pages can be referred by domain name and index name via ref role.

abstract generate(docnames: Optional[Iterable[str]] = None) → Tuple[List[Tuple[str, List[sphinx.domains.IndexEntry]]], bool][source]

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.

Python Domain

class sphinx.domains.python.PythonDomain(env: BuildEnvironment)[source]

Python language domain.

objects

modules

note_object(name: str, objtype: str, node_id: str, aliased: bool = False, location: Optional[Any] = None) → None[source]

Note a python object for cross reference.

New in version 2.1.

note_module(name: str, node_id: str, synopsis: str, platform: str, deprecated: bool) → None[source]

Note a python module for cross reference.

New in version 2.1.