Previous topic

Docutils markup API

Next topic

Doctree node classes added by Sphinx

This Page

Domain API


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, 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 since all object and cross-referencing information is stored on a BuildEnvironment instance, the object is also stored in the env.domaindata dict under the key 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.


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


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


Return an iterable of “object descriptions”, which are tuples with five 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)
    • 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, primary=False)

Return full name for given ObjType.

process_doc(env, docname, document)

Process a document after it is read by the environment.

resolve_xref(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 ‘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.


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

dangling_warnings = {}

role name -> a warning message if reference is missing

data_version = 0

data version, bump this when the format of 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

class, *roles, **attrs)

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

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.
  • 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().


Return entries for the index given by name. If docnames is given, restrict to entries referring to these docnames.

The return value is a tuple of (content, collapse), where collapse is a boolean that determines if sub-entries should start collapsed (for output formats that support collapsing sub-entries).

content is a sequence of (letter, entries) tuples, where letter is the “heading” for the given entries, usually the starting letter.

entries is a sequence of single entries, where a single 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 – sub-entry related type: 0 – normal entry 1 – entry with sub-entries 2 – 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 e.g. in LaTeX output.