Add app.override_domain().

doc/ext/appapi.rst

@@ -45,16 +45,24 @@ the following public API:
 
 .. method:: Sphinx.add_domain(domain)
 
-   Make the given *domain* (which must be a subclass of
+   Make the given *domain* (which must be a class; more precisely, a subclass of
    :class:`sphinx.domains.Domain`) known to Sphinx.
 
    .. XXX where is Domain documented?
 
    .. versionadded:: 1.0
 
+.. method:: Sphinx.override_domain(domain)
+
+   Make the given *domain* known to Sphinx, assuming that there is already a
+   domain with its ``.name``.  The new domain must be a subclass of the existing
+   one.
+
+   .. versionadded:: 1.0
+
 .. method:: Sphinx.add_event(name)
 
-   Register an event called *name*.
+   Register an event called *name*.  This is needed to be able to emit it.
 
 .. method:: Sphinx.add_node(node, **kwds)
 

sphinx/application.py

@@ -388,11 +388,18 @@ class Sphinx(object):
         roles.register_local_role(name, role)
 
     def add_domain(self, domain):
-        # XXX what about subclassing and overriding?
         if domain.name in self.domains:
             raise ExtensionError('domain %s already registered' % domain.name)
         self.domains[domain.name] = domain
 
+    def override_domain(self, domain):
+        if domain.name not in self.domains:
+            raise ExtensionError('domain %s not yet registered' % domain.name)
+        if not issubclass(domain, self.domains[domain.name]):
+            raise ExtensionError('new domain not a subclass of registered '
+                                 'domain' % domain.name)
+        self.domains[domain.name] = domain
+
     def add_directive_to_domain(self, domain, name, obj,
                                 content=None, arguments=None, **options):
         if domain not in self.domains: