Domain API
**********

class sphinx.domains.Domain(env: BuildEnvironment)

   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

      Add an object type.

   check_consistency() -> None

      Do consistency checks (**experimental**).

   clear_doc(docname: str) -> None

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

   directive(name: str) -> Callable

      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) -> str

      Get type of enumerable nodes (experimental).

   get_full_qualified_name(node: docutils.nodes.Element) -> str

      Return full qualified name for given node.

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

   get_type_name(type: sphinx.domains.ObjType, primary: bool = False) -> str

      Return full name for given ObjType.

   merge_domaindata(docnames: List[str], otherdata: Dict) -> None

      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

      Process a document after it is read by the environment.

   process_field_xref(pnode: sphinx.addnodes.pending_xref) -> None

      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]]

      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) -> docutils.nodes.Element

      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) -> 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]]]

      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 = None

      data value

   data_version = 0

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

   directives = {}

      directive name -> directive class

   enumerable_nodes = {}

      node_class -> (enum_node_type, title_getter)

   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 sphinx.domains.ObjType(lname: str, *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()".

class sphinx.domains.Index(domain: sphinx.domains.Domain)

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

   generate(docnames: Iterable[str] = None) -> Tuple[List[Tuple[str, List[sphinx.domains.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.
