sphinxcontrib.scaladomain — Documenting Scala APIs

This Sphinx extension provides a domain for documenting Scala APIs.

Getting Started


This extension can be installed from the Python Package Index:

pip install sphinxcontrib-scaladomain

Alternatively, you can clone the sphinx-contrib repository from BitBucket and install the extension directly from the repository:

hg clone http://bitbucket.org/birkenfeld/sphinx-contrib
cd sphinx-contrib/scaladomain
python setup.py install


Add sphinxcontrib.scaladomain to the configuration value extensions in your conf.py configuration file.


A list of prefixes that are ignored for sorting the Scala Package Index (e.g., if this is set to ['foo.'], then foo.bar is shown under B, not F). This can be handy if you document a project that consists of a single parent package. Works only for the HTML builder currently. Default is [].

Domain Markup

As most Sphinx domains, the Scala domain (name scl) provides a number of object description directives, used to describe specific objects provided by packages. Each directive requires one or more signatures to provide basic information about what is being described, and the content should be in 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:.

The Scala domain also provides roles that link back to these object descriptions. Both directive and role names contain the domain name and the directive name.

Describing Scala objects

The Scala domain provides the following directives for package declarations:

.. scl:package:: name

This directive marks the beginning of the description of a package. It does not create content.

This directive will also cause an entry in the Global Package Index.

The platform option, if present, is a comma-separated list of the platforms on which the module is available. (if it is available on all platforms, the option should be omitted). The keys are short identifiers; examples that are in use include “IRIX”, “Mac”, “Windows”, and “Unix”. It is important to use a key which has already been used when applicable.

The synopsis option should consist of one sentence describing the package’s purpose – it is currently only used in the Global Package Index.

The deprecated option can be given (with no value) to mark a package as deprecated; it will be designated as such in various locations then.

.. scl:currentpackage:: name

This directive tells Sphinx that the classes, objects etc. documented from here are in the given package (like scl:package), but it will not create index entries, an index in the Global Package Index, or a link target for scl:pkg. This is helpful in situations where documentation for things in a package is spread over multiple files or sections – one location has the scl:package directive, the others only scl:currentpackage.

Scala Signatures

Cross-referencing Scala objects

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


Reference a package.


Please contact the author or create an issue in the issue tracker of the sphinx-contrib repository, if you have found any bugs or miss some functionality. Patches are welcome!

Indices and tables