[Numpy-svn] r6137 - trunk/doc/sphinxext

numpy-svn@scip... numpy-svn@scip...
Thu Dec 4 17:06:40 CST 2008


Author: ptvirtan
Date: 2008-12-04 17:06:29 -0600 (Thu, 04 Dec 2008)
New Revision: 6137

Modified:
   trunk/doc/sphinxext/autosummary_generate.py
Log:
sphinxext: support autosummary:: directives in automodule docstrings

Modified: trunk/doc/sphinxext/autosummary_generate.py
===================================================================
--- trunk/doc/sphinxext/autosummary_generate.py	2008-12-04 03:21:51 UTC (rev 6136)
+++ trunk/doc/sphinxext/autosummary_generate.py	2008-12-04 23:06:29 UTC (rev 6137)
@@ -14,7 +14,7 @@
             ./ext/autosummary_generate.py -o source/generated source/*.rst
 
 """
-import glob, re, inspect, os, optparse
+import glob, re, inspect, os, optparse, pydoc
 from autosummary import import_by_name
 
 try:
@@ -104,7 +104,37 @@
 def get_documented(filenames):
     """
     Find out what items are documented in source/*.rst
+    See `get_documented_in_lines`.
+
+    """
+    documented = {}
+    for filename in filenames:
+        f = open(filename, 'r')
+        lines = f.read().splitlines()
+        documented.update(get_documented_in_lines(lines, filename=filename))
+        f.close()
+    return documented
+
+def get_documented_in_docstring(name, module=None, filename=None):
+    """
+    Find out what items are documented in the given object's docstring.
+    See `get_documented_in_lines`.
     
+    """
+    try:
+        obj, real_name = import_by_name(name)
+        lines = pydoc.getdoc(obj).splitlines()
+        return get_documented_in_lines(lines, module=name, filename=filename)
+    except AttributeError:
+        pass
+    except ImportError, e:
+        print "Failed to import '%s': %s" % (name, e)
+    return {}
+
+def get_documented_in_lines(lines, module=None, filename=None):
+    """
+    Find out what items are documented in the given lines
+    
     Returns
     -------
     documented : dict of list of (filename, title, keyword, toctree)
@@ -123,66 +153,66 @@
     toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$')
     
     documented = {}
+   
+    current_title = []
+    last_line = None
+    toctree = None
+    current_module = module
+    in_autosummary = False
     
-    for filename in filenames:
-        current_title = []
-        last_line = None
-        toctree = None
-        current_module = None
-        in_autosummary = False
+    for line in lines:
+        try:
+            if in_autosummary:
+                m = toctree_arg_re.match(line)
+                if m:
+                    toctree = m.group(1)
+                    continue
 
-        f = open(filename, 'r')
-        for line in f:
-            try:
-                if in_autosummary:
-                    m = toctree_arg_re.match(line)
-                    if m:
-                        toctree = m.group(1)
-                        continue
+                if line.strip().startswith(':'):
+                    continue # skip options
 
-                    if line.strip().startswith(':'):
-                        continue # skip options
-
-                    m = autosummary_item_re.match(line)
-                    if m:
-                        name = m.group(1).strip()
-                        if current_module and not name.startswith(current_module + '.'):
-                            name = "%s.%s" % (current_module, name)
-                        documented.setdefault(name, []).append(
-                            (filename, current_title, 'autosummary', toctree))
-                        continue
-                    if line.strip() == '':
-                        continue
-                    in_autosummary = False
-                
-                m = autosummary_re.match(line)
+                m = autosummary_item_re.match(line)
                 if m:
-                    in_autosummary = True
-                    continue
-                
-                m = autodoc_re.search(line)
-                if m:
-                    name = m.group(2).strip()
+                    name = m.group(1).strip()
                     if current_module and not name.startswith(current_module + '.'):
                         name = "%s.%s" % (current_module, name)
-                    if m.group(1) == "module":
-                        current_module = name
                     documented.setdefault(name, []).append(
-                        (filename, current_title, "auto" + m.group(1), None))
+                        (filename, current_title, 'autosummary', toctree))
                     continue
-
-                m = title_underline_re.match(line)
-                if m and last_line:
-                    current_title = last_line.strip()
+                if line.strip() == '':
                     continue
+                in_autosummary = False
 
-                m = module_re.match(line)
-                if m:
-                    current_module = m.group(2)
-                    continue
-            finally:
-                last_line = line
-    
+            m = autosummary_re.match(line)
+            if m:
+                in_autosummary = True
+                continue
+
+            m = autodoc_re.search(line)
+            if m:
+                name = m.group(2).strip()
+                if m.group(1) == "module":
+                    current_module = name
+                    documented.update(get_documented_in_docstring(
+                        name, filename=filename))
+                elif current_module and not name.startswith(current_module+'.'):
+                    name = "%s.%s" % (current_module, name)
+                documented.setdefault(name, []).append(
+                    (filename, current_title, "auto" + m.group(1), None))
+                continue
+
+            m = title_underline_re.match(line)
+            if m and last_line:
+                current_title = last_line.strip()
+                continue
+
+            m = module_re.match(line)
+            if m:
+                current_module = m.group(2)
+                continue
+        finally:
+            last_line = line
+
     return documented
 
 if __name__ == "__main__":



More information about the Numpy-svn mailing list