[Commit-gnuradio] [gnuradio] 01/23: grc: rewrite docstring extraction and allow for underscore in module name

[git]

This is an automated email from the git hooks/post-receive script.

jcorgan pushed a commit to branch master
in repository gnuradio.

commit f7add89403edcfdf8baa59c80b3e1d2b5c4ee307
Author: Sebastian Koslowski <address@hidden>
Date:   Tue Aug 18 16:54:06 2015 +0200

    grc: rewrite docstring extraction and allow for underscore in module name
---
 grc/python/extract_docs.py | 76 +++++++++++++++++++++++++++++-----------------
 1 file changed, 48 insertions(+), 28 deletions(-)

diff --git a/grc/python/extract_docs.py b/grc/python/extract_docs.py
index 47b2820..1124459 100644
--- a/grc/python/extract_docs.py
+++ b/grc/python/extract_docs.py
@@ -18,43 +18,58 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 
MA  02110-1301, USA
 """
 
 import re
+import itertools
 
-def _extract(key):
-    """
-    Extract the documentation from the python __doc__ strings.
-    If multiple modules match, combine the docs.
+
+def docstring_guess_from_key(key):
+    """Extract the documentation from the python __doc__ strings
+
+    By guessing module and constructor names from key
 
     Args:
         key: the block key
 
     Returns:
-        a string with documentation
+        a dict (block_name --> doc string)
     """
-    #extract matches
-    try:
-        module_name, constructor_name = key.split('_', 1)
-        module = __import__('gnuradio.'+module_name)
-        module = getattr(module, module_name)
-    except ImportError:
-            try:
-                    module_name, constructor_name = key.split('_', 1)
-                    module = __import__(module_name)
-            except: return ''
-    except:
-            return ''
-    pattern = constructor_name.replace('_', '_*').replace('x', '\w')
-    pattern_matcher = re.compile('^%s\w*$'%pattern)
-    matches = filter(lambda x: pattern_matcher.match(x), dir(module))
-    #combine all matches
-    doc_strs = list()
-    for match in matches:
+    doc_strings = dict()
+
+    in_tree = [key.partition('_')[::2] + (
+        lambda package: getattr(__import__('gnuradio.' + package), package),
+    )]
+
+    key_parts = key.split('_')
+    oot = [
+        ('_'.join(key_parts[:i]), '_'.join(key_parts[i:]), __import__)
+        for i in range(1, len(key_parts))
+    ]
+
+    for module_name, init_name, importer in itertools.chain(in_tree, oot):
+        if not module_name or not init_name:
+            continue
         try:
-            title = '   ---   ' + match + '   ---   '
-            doc_strs.append('\n\n'.join([title, getattr(module, 
match).__doc__]).strip())
-        except: pass
-    return '\n\n'.join(doc_strs)
+            module = importer(module_name)
+            break
+        except ImportError:
+            continue
+    else:
+        return doc_strings
+
+    pattern = re.compile(
+        '^' + init_name.replace('_', '_*').replace('x', r'\w') + r'\w*$'
+    )
+    for match in filter(pattern.match, dir(module)):
+        try:
+            doc_strings[match] = getattr(module, match).__doc__.strip()
+        except AttributeError:
+            continue
+
+    return doc_strings
+
 
 _docs_cache = dict()
+
+
 def extract(key):
     """
     Call the private extract and cache the result.
@@ -66,9 +81,14 @@ def extract(key):
         a string with documentation
     """
     if not _docs_cache.has_key(key):
-        _docs_cache[key] = _extract(key)
+        docstrings = docstring_guess_from_key(key)
+        _docs_cache[key] = '\n\n'.join(
+            '   ---   {0}   ---   \n\n{1}'.format(match, docstring)
+            for match, docstring in docstrings.iteritems()
+        )
     return _docs_cache[key]
 
+
 if __name__ == '__main__':
     import sys
     print extract(sys.argv[1])