1 files changed, 46 insertions, 4 deletions
diff --git a/doc/build/builder/autodoc_mods.py b/doc/build/builder/autodoc_mods.py
index 576b4c339..93e2596be 100644
--- a/doc/build/builder/autodoc_mods.py
+++ b/doc/build/builder/autodoc_mods.py
@@ -9,6 +9,30 @@ def autodoc_skip_member(app, what, name, obj, skip, options):
     else:
         return skip
 
+
+_convert_modname = {
+    "sqlalchemy.sql.sqltypes": "sqlalchemy.types",
+    "sqlalchemy.sql.type_api": "sqlalchemy.types",
+    "sqlalchemy.sql.schema": "sqlalchemy.schema",
+    "sqlalchemy.sql.elements": "sqlalchemy.sql.expression",
+    "sqlalchemy.sql.selectable": "sqlalchemy.sql.expression",
+    "sqlalchemy.sql.dml": "sqlalchemy.sql.expression",
+    "sqlalchemy.sql.ddl": "sqlalchemy.schema",
+    "sqlalchemy.sql.base": "sqlalchemy.sql.expression"
+}
+
+_convert_modname_w_class = {
+    ("sqlalchemy.engine.interfaces", "Connectable"): "sqlalchemy.engine"
+}
+
+def _adjust_rendered_mod_name(modname, objname):
+    if modname in _convert_modname:
+        return _convert_modname[modname]
+    elif (modname, objname) in _convert_modname_w_class:
+        return _convert_modname_w_class[(modname, objname)]
+    else:
+        return modname
+
 # im sure this is in the app somewhere, but I don't really
 # know where, so we're doing it here.
 _track_autodoced = {}
@@ -16,6 +40,24 @@ _inherited_names = set()
 def autodoc_process_docstring(app, what, name, obj, options, lines):
     if what == "class":
         _track_autodoced[name] = obj
+
+        # need to translate module names for bases, others
+        # as we document lots of symbols in namespace modules
+        # outside of their source
+        bases = []
+        for base in obj.__bases__:
+            if base is not object:
+                bases.append(":class:`%s.%s`" % (
+                        _adjust_rendered_mod_name(base.__module__, base.__name__),
+                        base.__name__))
+
+        if bases:
+            lines[:0] = [
+                        "Bases: %s" % (", ".join(bases)),
+                        ""
+            ]
+
+
     elif what in ("attribute", "method") and \
         options.get("inherited-members"):
         m = re.match(r'(.*?)\.([\w_]+)$', name)
@@ -35,15 +77,16 @@ def autodoc_process_docstring(app, what, name, obj, options, lines):
                         "    *inherited from the* :%s:`~%s.%s.%s` *%s of* :class:`~%s.%s`" % (
                                     "attr" if what == "attribute"
                                     else "meth",
-                                    supercls.__module__, supercls.__name__,
+                                    _adjust_rendered_mod_name(supercls.__module__, supercls.__name__),
+                                    supercls.__name__,
                                     attrname,
                                     what,
-                                    supercls.__module__, supercls.__name__
+                                    _adjust_rendered_mod_name(supercls.__module__, supercls.__name__),
+                                    supercls.__name__
                                 ),
                         ""
                     ]
 
-from docutils import nodes
 def missing_reference(app, env, node, contnode):
     if node.attributes['reftarget'] in _inherited_names:
         return node.children[0]
@@ -51,7 +94,6 @@ def missing_reference(app, env, node, contnode):
         return None
 
 
-
 def setup(app):
     app.connect('autodoc-skip-member', autodoc_skip_member)
     app.connect('autodoc-process-docstring', autodoc_process_docstring)