14. 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.