Add some domain documentation.

11 files changed, 446 insertions, 387 deletions

diff --git a/doc/conf.py b/doc/conf.py
index b0e847e7..03dac676 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -67,7 +67,7 @@ man_pages = [
 
 from sphinx import addnodes
 
-dir_sig_re = re.compile(r'\.\. ([^:]+)::(.*)$')
+dir_sig_re = re.compile(r'\.\. (.+?)::(.*)$')
 
 def parse_directive(env, sig, signode):
     if not sig.startswith('.'):
diff --git a/doc/config.rst b/doc/config.rst
index 089026d3..fae85fc4 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -182,6 +182,15 @@ General configuration
 
    .. versionadded:: 0.6
 
+.. confval:: default_domain
+
+   .. index:: default; domain
+
+   The name of the default :ref:`domain <domains>`.  Can also be ``None`` to
+   disable a default domain.  The default is ``'py'``.
+
+   .. versionadded:: 1.0
+
 .. confval:: default_role
 
    .. index:: default; role
diff --git a/doc/domains.rst b/doc/domains.rst
index 990a3ca4..50854746 100644
--- a/doc/domains.rst
+++ b/doc/domains.rst
@@ -1,6 +1,404 @@
+.. highlight:: rst
+
 .. _domains:
 
 Sphinx Domains
 ==============
 
-.. todo:: Write this section.
+.. versionadded:: 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 :term:`directive`\ s and
+:term:`role`\ s) to describe and link to :term:`object`\ s 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 :ref:`domain-api`.
+
+
+.. _basic-domain-markup:
+
+Basic Markup
+------------
+
+Most domains provide a number of :dfn:`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)
+      :noindex:
+
+      Spam or ham the foo.
+
+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.
+
+.. rubric:: 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 :confval:`default_domain` or this directive:
+
+.. directive:: .. default-domain:: name
+
+   Select a new default domain.  While the :confval:`default_domain` selects a
+   global default, this only has an effect within the same file.
+
+If no other default is selected, the Python domain (named ``py``) is the default
+one, mostly for compatibility with documentation written for older versions of
+Sphinx.
+
+Directives and roles that belong to the default domain can be mentioned without
+giving the domain name, i.e. ::
+
+   .. function:: pyfunc()
+
+      Describes a Python function.
+
+   Reference to :func:`pyfunc`.
+
+
+The Python Domain
+-----------------
+
+The Python domain (name **py**) provides the following directives for module
+declarations:
+
+.. directive:: .. py:module:: name
+
+   This directive marks the beginning of the description of a module (or package
+   submodule, in which case the name should be fully qualified, including the
+   package name).  It does not create content (like e.g. :dir:`py:class` does).
+
+   This directive will also cause an entry in the global module 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
+   module's purpose -- it is currently only used in the Global Module Index.
+
+   The ``deprecated`` option can be given (with no value) to mark a module as
+   deprecated; it will be designated as such in various locations then.
+
+
+.. directive:: .. py:currentmodule:: name
+
+   This directive tells Sphinx that the classes, functions etc. documented from
+   here are in the given module (like :dir:`py:module`), but it will not create
+   index entries, an entry in the Global Module Index, or a link target for
+   :role:`mod`.  This is helpful in situations where documentation for things in
+   a module is spread over multiple files or sections -- one location has the
+   :dir:`py:module` directive, the others only :dir:`py:currentmodule`.
+
+
+The following directives are provided for module and class contents:
+
+.. directive:: .. py:data:: name
+
+   Describes global data in a module, including both variables and values used
+   as "defined constants."  Class and object attributes are not documented
+   using this environment.
+
+.. directive:: .. py:exception:: name
+
+   Describes an exception class.  The signature can, but need not include
+   parentheses with constructor arguments.
+
+.. directive:: .. py:function:: name(signature)
+
+   Describes a module-level function.  The signature should include the
+   parameters, enclosing optional parameters in brackets.  Default values can be
+   given if it enhances clarity; see :ref:`signatures`.  For example::
+
+      .. py:function:: Timer.repeat([repeat=3[, number=1000000]])
+
+   Object methods are not documented using this directive. Bound object methods
+   placed in the module namespace as part of the public interface of the module
+   are documented using this, as they are equivalent to normal functions for
+   most purposes.
+
+   The description should include information about the parameters required and
+   how they are used (especially whether mutable objects passed as parameters
+   are modified), side effects, and possible exceptions.  A small example may be
+   provided.
+
+.. directive:: .. py:class:: name[(signature)]
+
+   Describes a class.  The signature can include parentheses with parameters
+   which will be shown as the constructor arguments.  See also
+   :ref:`signatures`.
+
+   Methods and attributes belonging to the class should be placed in this
+   directive's body.  If they are placed outside, the supplied name should
+   contain the class name so that cross-references still work.  Example::
+
+      .. py:class:: Foo
+         .. py:method:: quux()
+
+      -- or --
+
+      .. py:class:: Bar
+
+      .. py:method:: Bar.quux()
+
+   The first way is the preferred one.
+
+.. directive:: .. py:attribute:: name
+
+   Describes an object data attribute.  The description should include
+   information about the type of the data to be expected and whether it may be
+   changed directly.
+
+.. directive:: .. py:method:: name(signature)
+
+   Describes an object method.  The parameters should not include the ``self``
+   parameter.  The description should include similar information to that
+   described for ``function``.  See also :ref:`signatures`.
+
+.. directive:: .. py:staticmethod:: name(signature)
+
+   Like :dir:`py:method`, but indicates that the method is a static method.
+
+   .. versionadded:: 0.4
+
+.. directive:: .. py:classmethod:: name(signature)
+
+   Like :dir:`py:method`, but indicates that the method is a class method.
+
+   .. versionadded:: 0.6
+
+
+.. _signatures:
+
+Python Signatures
+~~~~~~~~~~~~~~~~~
+
+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
+~~~~~~~~~~~~~~~~
+
+.. versionadded:: 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
+
+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
+
+This will render like this:
+
+   .. py:function:: format_exception(etype, value, tb[, limit=None])
+      :noindex:
+
+      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
+
+
+The C Domain
+------------
+
+The C domain (name **c**) is suited for documentation of C API.
+
+.. directive:: .. c:function:: type name(signature)
+
+   Describes a C function. The signature should be given as in C, e.g.::
+
+      .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+   This is also used to describe function-like preprocessor macros.  The names
+   of the arguments should be given so they may be used in the description.
+
+   Note that you don't have to backslash-escape asterisks in the signature, as
+   it is not parsed by the reST inliner.
+
+.. directive:: .. c:member:: type name
+
+   Describes a C struct member. Example signature::
+
+      .. c:member:: PyObject* PyTypeObject.tp_bases
+
+   The text of the description should include the range of values allowed, how
+   the value should be interpreted, and whether the value can be changed.
+   References to structure members in text should use the ``member`` role.
+
+.. directive:: .. c:macro:: name
+
+   Describes a "simple" C macro.  Simple macros are macros which are used for
+   code expansion, but which do not take arguments so cannot be described as
+   functions.  This is not to be used for simple constant definitions.  Examples
+   of its use in the Python documentation include :c:macro:`PyObject_HEAD` and
+   :c:macro:`Py_BEGIN_ALLOW_THREADS`.
+
+.. directive:: .. c:type:: name
+
+   Describes a C type (whether defined by a typedef or struct). The signature
+   should just be the type name.
+
+.. directive:: .. c:var:: type name
+
+   Describes a global C variable.  The signature should include the type, such
+   as::
+
+      .. c:var:: PyObject* PyClass_Type
+
+
+The Standard Domain
+-------------------
+
+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
+:func:`~sphinx.application.Sphinx.add_object_type` API, are placed.
+
+There is a set of directives allowing documenting command-line programs:
+
+.. directive:: .. option:: name args, name args, ...
+
+   Describes a command line option or switch.  Option argument names should be
+   enclosed in angle brackets.  Example::
+
+      .. option:: -m <module>, --module <module>
+
+         Run a module as a script.
+
+   The directive will create a cross-reference target named after the *first*
+   option, referencable by :role:`option` (in the example case, you'd use
+   something like ``:option:`-m```).
+
+.. directive:: .. envvar:: name
+
+   Describes an environment variable that the documented code or program uses or
+   defines.  Referencable by :role:`envvar`.
+
+.. directive:: .. program:: name
+
+   Like :dir:`py:currentmodule`, this directive produces no output.  Instead, it
+   serves to notify Sphinx that all following :dir:`option` directives
+   document options for the program called *name*.
+
+   If you use :dir:`program`, you have to qualify the references in your
+   :role:`option` roles by the program name, so if you have the following
+   situation ::
+
+      .. program:: rm
+
+      .. option:: -r
+
+         Work recursively.
+
+      .. program:: svn
+
+      .. option:: -r revision
+
+         Specify the revision to work upon.
+
+   then ``:option:`rm -r``` would refer to the first option, while
+   ``:option:`svn -r``` would refer to the second one.
+
+   The program name may contain spaces (in case you want to document subcommands
+   like ``svn add`` and ``svn commit`` separately).
+
+   .. versionadded:: 0.5
+
+
+There is also a very generic object description directive, which is not tied to
+any domain:
+
+.. directive:: .. describe:: text
+               .. object:: text
+
+   This directive produces the same formatting as the specific ones provided by
+   domains, but does not create index entries or cross-referencing targets.
+   Example::
+
+      .. describe:: PAPER
+
+         You can set this variable to select a paper size.
diff --git a/doc/invocation.rst b/doc/invocation.rst
index e3ddc980..94b5db2e 100644
--- a/doc/invocation.rst
+++ b/doc/invocation.rst
@@ -14,7 +14,7 @@ you don't need to specify any *filenames*.
 
 The :program:`sphinx-build` script has several options:
 
-.. cmdoption:: -b buildername
+.. option:: -b buildername
 
    The most important option: it selects a builder.  The most common builders
    are:
@@ -53,26 +53,26 @@ The :program:`sphinx-build` script has several options:
    See :ref:`builders` for a list of all builders shipped with Sphinx.
    Extensions can add their own builders.
 
-.. cmdoption:: -a
+.. option:: -a
 
    If given, always write all output files.  The default is to only write output
    files for new and changed source files.  (This may not apply to all
    builders.)
 
-.. cmdoption:: -E
+.. option:: -E
 
    Don't use a saved :term:`environment` (the structure caching all
    cross-references), but rebuild it completely.  The default is to only read
    and parse source files that are new or have changed since the last run.
 
-.. cmdoption:: -t tag
+.. option:: -t tag
 
    Define the tag *tag*.  This is relevant for :dir:`only` directives that only
    include their content if this tag is set.
 
    .. versionadded:: 0.6
 
-.. cmdoption:: -d path
+.. option:: -d path
 
    Since Sphinx has to read and parse all source files before it can write an
    output file, the parsed source files are cached as "doctree pickles".
@@ -80,7 +80,7 @@ The :program:`sphinx-build` script has several options:
    the build directory; with this option you can select a different cache
    directory (the doctrees can be shared between all builders).
 
-.. cmdoption:: -c path
+.. option:: -c path
 
    Don't look for the :file:`conf.py` in the source directory, but use the given
    configuration directory instead.  Note that various other files and paths
@@ -90,13 +90,13 @@ The :program:`sphinx-build` script has several options:
 
    .. versionadded:: 0.3
 
-.. cmdoption:: -C
+.. option:: -C
 
    Don't look for a configuration file; only take options via the ``-D`` option.
 
    .. versionadded:: 0.5
 
-.. cmdoption:: -D setting=value
+.. option:: -D setting=value
 
    Override a configuration value set in the :file:`conf.py` file.  The value
    must be a string or dictionary value.  For the latter, supply the setting
@@ -106,42 +106,42 @@ The :program:`sphinx-build` script has several options:
    .. versionchanged:: 0.6
       The value can now be a dictionary value.
 
-.. cmdoption:: -A name=value
+.. option:: -A name=value
 
    Make the *name* assigned to *value* in the HTML templates.
 
    .. versionadded:: 0.5
 
-.. cmdoption:: -n
+.. option:: -n
 
    Run in nit-picky mode.  Currently, this generates warnings for all missing
    references.
 
-.. cmdoption:: -N
+.. option:: -N
 
    Do not emit colored output.  (On Windows, colored output is disabled in any
    case.)
 
-.. cmdoption:: -q
+.. option:: -q
 
    Do not output anything on standard output, only write warnings and errors to
    standard error.
 
-.. cmdoption:: -Q
+.. option:: -Q
 
    Do not output anything on standard output, also suppress warnings.  Only
    errors are written to standard error.
 
-.. cmdoption:: -w file
+.. option:: -w file
 
    Write warnings (and errors) to the given file, in addition to standard error.
 
-.. cmdoption:: -W
+.. option:: -W
 
    Turn warnings into errors.  This means that the build stops at the first
    warning and ``sphinx-build`` exits with exit status 1.
 
-.. cmdoption:: -P
+.. option:: -P
 
    (Useful for debugging only.)  Run the Python debugger, :mod:`pdb`, if an
    unhandled exception occurs while building.
diff --git a/doc/markup/desc.rst b/doc/markup/desc.rst
deleted file mode 100644
index eb7de7c3..00000000
--- a/doc/markup/desc.rst
+++ /dev/null
@@ -1,364 +0,0 @@
-.. highlight:: rest
-
-Module-specific markup
-----------------------
-
-The markup described in this section is used to provide information about a
-module being documented.  Normally this markup appears after a title heading; a
-typical module section might start like this::
-
-   :mod:`parrot` -- Dead parrot access
-   ===================================
-
-   .. module:: parrot
-      :platform: Unix, Windows
-      :synopsis: Analyze and reanimate dead parrots.
-   .. moduleauthor:: Eric Cleese <eric@python.invalid>
-   .. moduleauthor:: John Idle <john@python.invalid>
-
-
-The directives you can use for module declarations are:
-
-.. directive:: .. module:: name
-
-   This directive marks the beginning of the description of a module (or package
-   submodule, in which case the name should be fully qualified, including the
-   package name).  It does not create content (like e.g. :dir:`class` does).
-
-   This directive will also cause an entry in the global module 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
-   module's purpose -- it is currently only used in the Global Module Index.
-
-   The ``deprecated`` option can be given (with no value) to mark a module as
-   deprecated; it will be designated as such in various locations then.
-
-
-.. directive:: .. currentmodule:: name
-
-   This directive tells Sphinx that the classes, functions etc. documented from
-   here are in the given module (like :dir:`module`), but it will not create
-   index entries, an entry in the Global Module Index, or a link target for
-   :role:`mod`.  This is helpful in situations where documentation for things in
-   a module is spread over multiple files or sections -- one location has the
-   :dir:`module` directive, the others only :dir:`currentmodule`.
-
-
-.. directive:: .. moduleauthor:: name <email>
-
-   The ``moduleauthor`` directive, which can appear multiple times, names the
-   authors of the module code, just like ``sectionauthor`` names the author(s)
-   of a piece of documentation.  It too only produces output if the
-   :confval:`show_authors` configuration value is True.
-
-
-.. note::
-
-   It is important to make the section title of a module-describing file
-   meaningful since that value will be inserted in the table-of-contents trees
-   in overview files.
-
-
-.. _desc-units:
-
-Object descriptions
--------------------
-
-.. XXX generalize for domains
-
-There are a number of 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:``.  The
-following example shows all of the features of this directive type::
-
-    .. function:: spam(eggs)
-                  ham(eggs)
-       :noindex:
-
-       Spam or ham the foo.
-
-The signatures of object methods or data attributes should always include the
-type name (``.. method:: FileInput.input(...)``), even if it is obvious from the
-context which type they belong to; this is to enable consistent
-cross-references.  If you describe methods belonging to an abstract protocol,
-such as "context managers", include a (pseudo-)type name too to make the
-index entries more informative.
-
-The directives are:
-
-.. XXX update this
-
-.. directive:: .. cfunction:: type name(signature)
-
-   Describes a C function. The signature should be given as in C, e.g.::
-
-      .. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
-
-   This is also used to describe function-like preprocessor macros.  The names
-   of the arguments should be given so they may be used in the description.
-
-   Note that you don't have to backslash-escape asterisks in the signature,
-   as it is not parsed by the reST inliner.
-
-.. directive:: .. cmember:: type name
-
-   Describes a C struct member. Example signature::
-
-      .. cmember:: PyObject* PyTypeObject.tp_bases
-
-   The text of the description should include the range of values allowed, how
-   the value should be interpreted, and whether the value can be changed.
-   References to structure members in text should use the ``member`` role.
-
-.. directive:: .. cmacro:: name
-
-   Describes a "simple" C macro.  Simple macros are macros which are used
-   for code expansion, but which do not take arguments so cannot be described as
-   functions.  This is not to be used for simple constant definitions.  Examples
-   of its use in the Python documentation include :c:macro:`PyObject_HEAD` and
-   :c:macro:`Py_BEGIN_ALLOW_THREADS`.
-
-.. directive:: .. ctype:: name
-
-   Describes a C type. The signature should just be the type name.
-
-.. directive:: .. cvar:: type name
-
-   Describes a global C variable.  The signature should include the type, such
-   as::
-
-      .. cvar:: PyObject* PyClass_Type
-
-.. directive:: .. data:: name
-
-   Describes global data in a module, including both variables and values used
-   as "defined constants."  Class and object attributes are not documented
-   using this environment.
-
-.. directive:: .. exception:: name
-
-   Describes an exception class.  The signature can, but need not include
-   parentheses with constructor arguments.
-
-.. directive:: .. function:: name(signature)
-
-   Describes a module-level function.  The signature should include the
-   parameters, enclosing optional parameters in brackets.  Default values can be
-   given if it enhances clarity; see :ref:`signatures`.  For example::
-
-      .. function:: Timer.repeat([repeat=3[, number=1000000]])
-
-   Object methods are not documented using this directive. Bound object methods
-   placed in the module namespace as part of the public interface of the module
-   are documented using this, as they are equivalent to normal functions for
-   most purposes.
-
-   The description should include information about the parameters required and
-   how they are used (especially whether mutable objects passed as parameters
-   are modified), side effects, and possible exceptions.  A small example may be
-   provided.
-
-.. directive:: .. class:: name[(signature)]
-
-   Describes a class.  The signature can include parentheses with parameters
-   which will be shown as the constructor arguments.  See also
-   :ref:`signatures`.
-
-   Methods and attributes belonging to the class should be placed in this
-   directive's body.  If they are placed outside, the supplied name should
-   contain the class name so that cross-references still work.  Example::
-
-      .. class:: Foo
-         .. method:: quux()
-
-      -- or --
-
-      .. class:: Bar
-
-      .. method:: Bar.quux()
-
-   The first way is the preferred one.
-
-.. directive:: .. attribute:: name
-
-   Describes an object data attribute.  The description should include
-   information about the type of the data to be expected and whether it may be
-   changed directly.
-
-.. directive:: .. method:: name(signature)
-
-   Describes an object method.  The parameters should not include the ``self``
-   parameter.  The description should include similar information to that
-   described for ``function``.  See also :ref:`signatures`.
-
-.. directive:: .. staticmethod:: name(signature)
-
-   Like :dir:`method`, but indicates that the method is a static method.
-
-   .. versionadded:: 0.4
-
-.. directive:: .. classmethod:: name(signature)
-
-   Like :dir:`method`, but indicates that the method is a class method.
-
-   .. versionadded:: 0.6
-
-
-.. _signatures:
-
-Signatures
-~~~~~~~~~~
-
-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::
-
-   .. 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::
-
-   .. 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::
-
-   .. function:: compile(source : string[, filename, symbol]) -> ast object
-
-
-Info field lists
-~~~~~~~~~~~~~~~~
-
-.. versionadded:: 0.4
-
-.. XXX this is only correct for Python
-
-Inside 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::
-
-   .. 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
-
-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
-
-This will render like this:
-
-   .. function:: format_exception(etype, value, tb[, limit=None])
-      :noindex:
-
-      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
-
-
-Command-line program markup
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There is a set of directives allowing documenting command-line programs:
-
-.. directive:: .. cmdoption:: name args, name args, ...
-
-   Describes a command line option or switch.  Option argument names should be
-   enclosed in angle brackets.  Example::
-
-      .. cmdoption:: -m <module>, --module <module>
-
-         Run a module as a script.
-
-   The directive will create a cross-reference target named after the *first*
-   option, referencable by :role:`option` (in the example case, you'd use
-   something like ``:option:`-m```).
-
-.. directive:: .. envvar:: name
-
-   Describes an environment variable that the documented code or program uses or
-   defines.
-
-
-.. directive:: .. program:: name
-
-   Like :dir:`currentmodule`, this directive produces no output.  Instead, it
-   serves to notify Sphinx that all following :dir:`cmdoption` directives
-   document options for the program called *name*.
-
-   If you use :dir:`program`, you have to qualify the references in your
-   :role:`option` roles by the program name, so if you have the following
-   situation ::
-
-      .. program:: rm
-
-      .. cmdoption:: -r
-
-         Work recursively.
-
-      .. program:: svn
-
-      .. cmdoption:: -r revision
-
-         Specify the revision to work upon.
-
-   then ``:option:`rm -r``` would refer to the first option, while
-   ``:option:`svn -r``` would refer to the second one.
-
-   The program name may contain spaces (in case you want to document subcommands
-   like ``svn add`` and ``svn commit`` separately).
-
-   .. versionadded:: 0.5
-
-
-Custom object types
-~~~~~~~~~~~~~~~~~~~
-
-There is also a generic version of these directives:
-
-.. directive:: .. describe:: text
-
-   This directive produces the same formatting as the specific ones explained
-   above but does not create index entries or cross-referencing targets.  It is
-   used, for example, to describe the directives in this document. Example::
-
-      .. describe:: opcode
-
-         Describes a Python bytecode instruction.
-
-Extensions may add more directives like that, using the
-:func:`~sphinx.application.Sphinx.add_object_type` method.
diff --git a/doc/markup/index.rst b/doc/markup/index.rst
index f1bc27d1..9492456d 100644
--- a/doc/markup/index.rst
+++ b/doc/markup/index.rst
@@ -9,8 +9,9 @@ markup.  This section contains the reference material for these facilities.
 .. toctree::
 
    toctree
-   desc
    para
    code
    inline
    misc
+
+More markup is added by :ref:`domains`.
diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst
index 7db403ab..b0e78dc2 100644
--- a/doc/markup/misc.rst
+++ b/doc/markup/misc.rst
@@ -39,7 +39,7 @@ At the moment, these metadata fields are recognized:
 Meta-information markup
 -----------------------
 
-.. directive:: sectionauthor
+.. directive:: .. sectionauthor:: name <email>
 
    Identifies the author of the current section.  The argument should include
    the author's name such that it can be used for presentation and email
@@ -54,6 +54,14 @@ Meta-information markup
    output.
 
 
+.. directive:: .. codeauthor:: name <email>
+
+   The :dir:`codeauthor` directive, which can appear multiple times, names the
+   authors of the described code, just like :dir:`sectionauthor` names the
+   author(s) of a piece of documentation.  It too only produces output if the
+   :confval:`show_authors` configuration value is True.
+
+
 .. _tags:
 
 Including content based on tags
diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst
index d85a0de0..af2fc223 100644
--- a/doc/markup/toctree.rst
+++ b/doc/markup/toctree.rst
@@ -147,7 +147,8 @@ The special document names (and pages generated for them) are:
   page, respectively.
 
   The general index is populated with entries from modules, all index-generating
-  :ref:`object descriptions <desc-units>`, and from :dir:`index` directives.
+  :ref:`object descriptions <basic-domain-markup>`, and from :dir:`index`
+  directives.
 
   The module index contains one entry per :dir:`module` directive.
 
diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index 8aa1574d..d3e40dee 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -113,11 +113,13 @@ Documenting objects
 -------------------
 
 
+
+
 Topics to be covered
 --------------------
 
 - Autodoc
-- Domains
+- Other Domains
 - Basic configuration
 - Static files
 - Selecting a theme
diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py
index 448498f8..138d10c8 100644
--- a/sphinx/directives/other.py
+++ b/sphinx/directives/other.py
@@ -127,6 +127,8 @@ class Author(Directive):
             text = _('Section author: ')
         elif self.name == 'moduleauthor':
             text = _('Module author: ')
+        elif self.name == 'codeauthor':
+            text = _('Code author: ')
         else:
             text = _('Author: ')
         emph += nodes.Text(text, text)
@@ -368,6 +370,7 @@ class Only(Directive):
 directives.register_directive('toctree', TocTree)
 directives.register_directive('sectionauthor', Author)
 directives.register_directive('moduleauthor', Author)
+directives.register_directive('codeauthor', Author)
 directives.register_directive('index', Index)
 directives.register_directive('deprecated', VersionChange)
 directives.register_directive('versionadded', VersionChange)
diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py
index da28f956..8b254e15 100644
--- a/sphinx/domains/std.py
+++ b/sphinx/domains/std.py
@@ -330,7 +330,8 @@ class StandardDomain(Domain):
 
     directives = {
         'program': Program,
-        'cmdoption': Cmdoption,
+        'cmdoption': Cmdoption,  # old name for backwards compatibility
+        'option': Cmdoption,
         'envvar': EnvVar,
         'glossary': Glossary,
         'productionlist': ProductionList,