1.2.3. Domains¶

A domain is a collection of explicit and inline markup (reStructuredText Directives and Roles) to describe and link to objects belonging together, e.g. elements of a programming language. Directive and role names in a domain have names like domain:name, e.g. .. c:function:: int main(int argc, char **argv, char **env) or :c:func:`main`.

An object is the basic building block of Sphinx documentation. Every “object directive” (e.g. function or object) creates such a block; and most objects can be cross-referenced to.

The Standard Domain collects all markup that does not warrant a domain of its own. Its directives and roles are not prefixed with a domain name.

There is a set of directives allowing documenting command-line programs:

Table 1.1 Sphinx directives for command-line programs¶
short description	directive (target)	role (reference)
`Following document options for the program.`	`.. program:: name`
`Describes a command line argument or switch.`	`.. option:: name args, ...`	:option:`name arg`
`Describes an environment variable.`	`.. envvar:: name`	:envvar:`name`

There is also a very generic object description directive, which is not tied to any domain. This directive produces the same formatting as the specific ones provided by domains, but does not create index entries or cross-referencing targets:

Table 1.2 Sphinx directives for unspecific objects without referencing¶
short description	directive (target)	role (reference)
`Describes an unspecific element.`	`.. describe:: text`
`Describes an unspecific object.`	`.. object:: text`

Originally, Sphinx was conceived for a single project, the documentation of the Python language. Shortly afterwards, it was made available for everyone as a documentation tool, but the documentation of Python modules remained deeply built in – the most fundamental directives, like function, were designed for Python objects.

Since Sphinx has become somewhat popular, interest developed in using it for many different purposes: C/C++ projects, JavaScript, or even reStructuredText markup (like in this documentation). The following specific domains are provided by Sphinx (without additional extensions):

The C Domain (name c)
The C++ Domain (name cpp)
The JavaScript Domain (name js)
The Math Domain (name math)
The Python Domain (name py)
The reStructuredText Domain (name rst)