Glossary

configuration directory

The directory containing conf.py. By default, this is the same as the source directory, but can be set differently with the -c command-line option.

directive

A reStructuredText markup element that allows marking a block of content with special meaning. Directives are supplied not only by docutils, but Sphinx and custom extensions can add their own. The basic directive syntax looks like this:

.. directivename:: argument ...
   :option: value

   Content of the directive.

See for more information.

document name

Since reST source files can have different extensions (some people like .txt, some like .rst – the extension can be configured with ) and different OSes have different path separators, Sphinx abstracts them are always relative to the , the extension is stripped, and path separators are converted to slashes. All values, parameters and such referring to “documents” expect such document names.

Examples for document names are index, library/zipfile, or reference/datamodel/types. Note that there is no leading or trailing slash.

domain

A domain is a collection of markup (reStructuredText s and ) to describe and link to 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.

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. For more information about domains, see the chapter .

environment

A structure where information about all documents under the root is saved, and used for cross-referencing. The environment is pickled after the parsing stage, so that successive runs only need to read and parse new and changed documents.

FSL

A neuroimaging workbench with tools for fMRI, structural and especially dwi processing.

master document

The document that contains the root directive.

object

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

role

A reStructuredText markup element that allows marking a piece of text. Like directives, roles are extensible. The basic syntax looks like this: :rolename:`content`.

source directory

The directory which, including its subdirectories, contains all source files for one Sphinx project.