- reorganize docs so expression, schema are broken out into subfiles, they're too big

- fix the targeting of module names moved around by using custom handlers for "Bases", etc.

1 files changed, 33 insertions, 3 deletions

diff --git a/doc/build/builder/autodoc_mods.py b/doc/build/builder/autodoc_mods.py
index 576b4c339..04afb03a7 100644
--- a/doc/build/builder/autodoc_mods.py
+++ b/doc/build/builder/autodoc_mods.py
@@ -9,6 +9,19 @@ def autodoc_skip_member(app, what, name, obj, skip, options):
     else:
         return skip
 
+
+def _adjust_rendered_mod_name(modname, objname):
+    modname = modname.replace("sqlalchemy.sql.sqltypes", "sqlalchemy.types")
+    modname = modname.replace("sqlalchemy.sql.type_api", "sqlalchemy.types")
+    modname = modname.replace("sqlalchemy.sql.schema", "sqlalchemy.schema")
+    modname = modname.replace("sqlalchemy.sql.elements", "sqlalchemy.sql.expression")
+    modname = modname.replace("sqlalchemy.sql.selectable", "sqlalchemy.sql.expression")
+    modname = modname.replace("sqlalchemy.sql.dml", "sqlalchemy.sql.expression")
+    modname = modname.replace("sqlalchemy.sql.ddl", "sqlalchemy.schema")
+    modname = modname.replace("sqlalchemy.sql.base", "sqlalchemy.sql.expression")
+
+    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 +29,22 @@ _inherited_names = set()
 def autodoc_process_docstring(app, what, name, obj, options, lines):
     if what == "class":
         _track_autodoced[name] = obj
+
+        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.insert(0,
+                        "Bases: %s" % (
+                            ", ".join(bases)
+                        ))
+            lines.insert(1, "")
+
+
     elif what in ("attribute", "method") and \
         options.get("inherited-members"):
         m = re.match(r'(.*?)\.([\w_]+)$', name)
@@ -35,10 +64,12 @@ 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__
                                 ),
                         ""
                     ]
@@ -51,7 +82,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)