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:
short description |
directive (target) |
role (reference) |
---|---|---|
|
||
|
|
|
|
|
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:
short description |
directive (target) |
role (reference) |
---|---|---|
|
||
|
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)