From 76eb148770f42b260330dea4a83b40352b2d06eb Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Sat, 27 Feb 2010 23:13:51 +0100
Subject: [PATCH] Add app.override_domain().

---
 doc/ext/appapi.rst    | 12 ++++++++++--
 sphinx/application.py |  9 ++++++++-
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index 8df028e1d..b536fd985 100644
--- a/doc/ext/appapi.rst
+++ b/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)
 
diff --git a/sphinx/application.py b/sphinx/application.py
index 7d4e3cac8..860affbb6 100644
--- a/sphinx/application.py
+++ b/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: