5.6.2.3. sphinx.domains.std.Domain

class sphinx.domains.std.Domain(env)[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, IOError is raised and the pickled environment is discarded.

5.6.2.3.1. Methods

__init__(env)
clear_doc(docname) Remove traces of a document in the domain-specific inventories.
directive(name) Return a directive adapter class that always gives the registered directive its full name (‘domain:name’) as self.name.
get_objects() Return an iterable of “object descriptions”, which are tuples with
get_type_name(type[, primary]) Return full name for given ObjType.
merge_domaindata(docnames, otherdata) Merge in data regarding docnames from a different domaindata inventory (coming from a subprocess in parallel builds).
process_doc(env, docname, document) Process a document after it is read by the environment.
resolve_any_xref(env, fromdocname, builder, ...) Resolve the pending_xref node with the given target.
resolve_xref(env, fromdocname, builder, typ, ...) Resolve the pending_xref node with the given typ and target.
role(name) Return a role adapter function that always gives the registered role its full name (‘domain:name’) as the first argument.

5.6.2.3.2. Attributes

dangling_warnings role name -> a warning message if reference is missing
data_version data version, bump this when the format of self.data changes
directives directive name -> directive class
indices a list of Index subclasses
initial_data 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 type (usually directive) name -> ObjType instance
roles role name -> role callable