Sphinx Domains

New in version 1.0.

What is a Domain?

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

While this was always possible, it is now much easier to easily support documentation of projects using different programming languages or even ones not supported by the main Sphinx distribution, by providing a domain for every such purpose.

A domain is a collection of 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. py:function. Domains can also provide custom indices (like the Python Module Index).

Having domains means that there are no naming problems when one set of documentation wants to refer to e.g. C++ and Python classes. It also means that extensions that support the documentation of whole new languages are much easier to write.

This section describes what the domains that come with Sphinx provide. The domain API is documented as well, in the section Domain API.

Basic Markup

Most domains provide a number of object description directives, used to describe specific objects provided by modules. Each directive requires one or more signatures to provide basic information about what is being described, and the content should be the description. The basic version makes entries in the general index; if no index entry is desired, you can give the directive option flag :noindex:. An example using a Python domain directive:

.. py:function:: spam(eggs)
                 ham(eggs)

   Spam or ham the foo.

This describes the two Python functions spam and ham. (Note that when signatures become too long, you can break them if you add a backslash to lines that are continued in the next line. Example:

.. py:function:: filterwarnings(action, message='', category=Warning, \
                                module='', lineno=0, append=False)
   :noindex:

(This example also shows how to use the :noindex: flag.)

The domains also provide roles that link back to these object descriptions. For example, to link to one of the functions described in the example above, you could say

The function :py:func:`spam` does a similar thing.

As you can see, both directive and role names contain the domain name and the directive name.

Default Domain

To avoid having to writing the domain name all the time when you e.g. only describe Python objects, a default domain can be selected with either the config value primary_domain or this directive:

.. default-domain:: name

For cross-reference roles provided by domains, the same facilities exist as for general cross-references. See Cross-referencing syntax.

In short:

• You may supply an explicit title and reference target: :role:`title <target>` will refer to target, but the link text will be title.
• If you prefix the content with !, no reference/hyperlink will be created.
• If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only display get as the link text.

The Python Domain

The Python domain (name py) provides the following directives for module declarations:

.. py:module:: name

Signatures of functions, methods and class constructors can be given like they would be written in Python, with the exception that optional parameters can be indicated by brackets:

.. py:function:: compile(source[, filename[, symbol]])

It is customary to put the opening bracket before the comma. In addition to this “nested” bracket style, a “flat” style can also be used, due to the fact that most optional parameters can be given independently:

.. py:function:: compile(source[, filename, symbol])

Default values for optional arguments can be given (but if they contain commas, they will confuse the signature parser). Python 3-style argument annotations can also be given as well as return type annotations:

.. py:function:: compile(source : string[, filename, symbol]) -> ast object

Info field lists

New in version 0.4.

Inside Python object description directives, reST field lists with these fields are recognized and formatted nicely:

• param, parameter, arg, argument, key, keyword: Description of a parameter.
• type: Type of a parameter.
• raises, raise, except, exception: That (and when) a specific exception is raised.
• var, ivar, cvar: Description of a variable.
• returns, return: Description of the return value.
• rtype: Return type.

The field names must consist of one of these keywords and an argument (except for returns and rtype, which do not need an argument). This is best explained by an example:

.. py:function:: format_exception(etype, value, tb[, limit=None])

   Format the exception with a traceback.

   :param etype: exception type
   :param value: exception value
   :param tb: traceback object
   :param limit: maximum number of stack frames to show
   :type limit: integer or None
   :rtype: list of strings

This will render like this:

format_exception(etype, value, tb[, limit=None])

Format the exception with a traceback.

Parameters:	etype – exception type value – exception value tb – traceback object limit (integer or None) – maximum number of stack frames to show
Return type:	list of strings

It is also possible to combine parameter type and description, if the type is a single word, like this:

:param integer limit: maximum number of stack frames to show

Cross-referencing Python objects

The following roles refer to objects in modules and are possibly hyperlinked if a matching identifier is found:

:py:mod:

The C domain (name c) is suited for documentation of C API.

.. c:function:: type name(signature)

The following roles create cross-references to C-language constructs if they are defined in the documentation:

:c:data:

The C++ domain (name cpp) supports documenting C++ projects.

The following directives are available:

.. cpp:class:: signatures

The so-called “standard” domain collects all markup that doesn’t warrant a domain of its own. Its directives and roles are not prefixed with a domain name.

The standard domain is also where custom object descriptions, added using the add_object_type() API, are placed.

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

.. option:: name args, name args, ...

The JavaScript domain (name js) provides the following directives:

.. js:function:: name(signature)

The reStructuredText domain (name rst) provides the following directives:

.. rst:directive:: name

The sphinx-contrib repository contains more domains available as extensions; currently a Ruby and an Erlang domain.