From 0452388ef0c856d742bf491d9982961e85b4dbd2 Mon Sep 17 00:00:00 2001
From: Stefan van der Walt <stefan@sun.ac.za>
Date: Thu, 24 Sep 2009 17:47:25 +0200
Subject: [PATCH] Generate cleaner API reference with autosummary tables.

---
 doc/source/conf.py  |  3 ++-
 doc/tools/apigen.py | 52 +++++++++++++++++++++++++++------------------
 2 files changed, 33 insertions(+), 22 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 50d9e3e7..29606d9d 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -25,7 +25,8 @@ sys.path.append(os.path.join(curpath, '../ext'))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'numpydoc']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'numpydoc',
+              'sphinx.ext.autosummary']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/doc/tools/apigen.py b/doc/tools/apigen.py
index 55d03075..4e6b70f3 100644
--- a/doc/tools/apigen.py
+++ b/doc/tools/apigen.py
@@ -157,11 +157,9 @@ class ApiDocWriter(object):
     def _path2uri(self, dirpath):
         ''' Convert directory path to uri '''
         package_dir = self.package_name.replace('.', os.path.sep)
-        print dirpath, self.root_path
         relpath = dirpath.replace(self.root_path, package_dir)
         if relpath.startswith(os.path.sep):
             relpath = relpath[1:]
-        print "uri: ", relpath.replace(os.path.sep, '.')
         return relpath.replace(os.path.sep, '.')
 
     def _parse_module(self, uri):
@@ -213,18 +211,18 @@ class ApiDocWriter(object):
         # get the names of all classes and functions
         functions, classes = self._parse_module(uri)
         if not len(functions) and not len(classes):
-            print 'WARNING: Empty -',uri  # dbg
+            print 'WARNING: Empty -', uri  # dbg
             return ''
 
         # Make a shorter version of the uri that omits the package name for
-        # titles 
+        # titles
         uri_short = re.sub(r'^%s\.' % self.package_name,'',uri)
-        
+
         ad = '.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n'
 
         chap_title = uri_short
-        ad += (chap_title+'\n'+ self.rst_section_levels[1] * len(chap_title)
-               + '\n\n')
+        #ad += (chap_title+'\n'+ self.rst_section_levels[1] * len(chap_title)
+        #       + '\n\n')
 
         # Set the chapter title to read 'module' for all modules except for the
         # main packages
@@ -232,7 +230,7 @@ class ApiDocWriter(object):
             title = 'Module: :mod:`' + uri_short + '`'
         else:
             title = ':mod:`' + uri_short + '`'
-        ad += title + '\n' + self.rst_section_levels[2] * len(title)
+        ad += title + '\n' + self.rst_section_levels[1] * len(title)
 
         if len(classes):
             ad += '\nInheritance diagram for ``%s``:\n\n' % uri
@@ -243,12 +241,12 @@ class ApiDocWriter(object):
         ad += '\n.. currentmodule:: ' + uri + '\n'
         multi_class = len(classes) > 1
         multi_fx = len(functions) > 1
-        if multi_class:
-            ad += '\n' + 'Classes' + '\n' + \
-                  self.rst_section_levels[2] * 7 + '\n'
-        elif len(classes) and multi_fx:
-            ad += '\n' + 'Class' + '\n' + \
-                  self.rst_section_levels[2] * 5 + '\n'
+#        if multi_class:
+#            ad += '\n' + 'Classes' + '\n' + \
+#                  self.rst_section_levels[2] * 7 + '\n'
+#        elif len(classes) and multi_fx:
+#            ad += '\n' + 'Class' + '\n' + \
+#                  self.rst_section_levels[2] * 5 + '\n'
         for c in classes:
             ad += '\n:class:`' + c + '`\n' \
                   + self.rst_section_levels[multi_class + 2 ] * \
@@ -261,15 +259,23 @@ class ApiDocWriter(object):
                   '  :inherited-members:\n' \
                   '\n' \
                   '  .. automethod:: __init__\n'
-        if multi_fx:
-            ad += '\n' + 'Functions' + '\n' + \
-                  self.rst_section_levels[2] * 9 + '\n\n'
-        elif len(functions) and multi_class:
-            ad += '\n' + 'Function' + '\n' + \
-                  self.rst_section_levels[2] * 8 + '\n\n'
+#        if multi_fx:
+        ad += '\n' + 'Functions' + '\n' + \
+              self.rst_section_levels[2] * 9 + '\n\n'
+#        elif len(functions) and multi_class:
+#            ad += '\n' + 'Function' + '\n' + \
+#                  self.rst_section_levels[2] * 8 + '\n\n'
+        ad += '.. autosummary::\n\n'
+        for f in functions:
+            ad += '   ' + uri + '.' + f + '\n'
+        ad += '\n'
+
         for f in functions:
             # must NOT exclude from index to keep cross-refs working
-            ad += '\n.. autofunction:: ' + uri + '.' + f + '\n\n'
+            full_f = uri + '.' + f
+            ad += f + '\n'
+            ad += self.rst_section_levels[3] * len(f) + '\n'
+            ad += '\n.. autofunction:: ' + full_f + '\n\n'
         return ad
 
     def _survives_exclude(self, matchstr, match_type):
@@ -429,6 +435,10 @@ class ApiDocWriter(object):
         idx = open(path,'wt')
         w = idx.write
         w('.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n')
+
+        title = self.package_name + " API Reference"
+        w(title + "\n")
+        w("=" * len(title) + "\n\n")
         w('.. toctree::\n\n')
         for f in self.written_modules:
             w('   %s\n' % os.path.join(relpath,f))