.. include:: /include/substitutions.txt

*******
Domains
*******

Domains are areas of a document that have their own syntax and meaning.  For example,
the interpreted text role ``:cpp:expr:`` simply indicates what is contained in the
subsequent backquotes has a syntax known to (and parsed by) the logic in the

    sphinx/domains/cpp.py

module.  That's where the parsing logic for that domain lives.  It simply tells the
parser which polymorphic parser to select from in order to parse the contents of
the backquotes.

Domains can manage:

- interpreted text roles (which look like this:  ``:cpp:expr:``, where ``cpp`` is
  the domain module and ``expr`` is name of the parser.

- directives (which look like this:  ``.. cpp:some_directive::`` and its content also
  has its own syntax and is parsed by ``cpp.py::some_directive`` directive parser.
  Parsing implies computing a set of docutils nodes that then get appended to
  ``self.parent.children`` nodes list.

If you have some special kind of patterns you want Sphinx to take special action
with, adding your own domain is a way of adding your own brand of specialty-parsing
to Sphinx.