Move docstring processing to an util module.

3 files changed, 63 insertions, 74 deletions

diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py
index ddea1e44..55f0d58f 100644
--- a/sphinx/ext/autodoc.py
+++ b/sphinx/ext/autodoc.py
@@ -23,6 +23,7 @@ from docutils.statemachine import ViewList
 
 from sphinx.util import rpartition, nested_parse_with_titles
 from sphinx.pycode import ModuleAnalyzer, PycodeError
+from sphinx.util.docstrings import prepare_docstring
 
 clstypes = (type, ClassType)
 try:
@@ -172,35 +173,6 @@ def isdescriptor(x):
     return False
 
 
-def prepare_docstring(s):
-    """
-    Convert a docstring into lines of parseable reST.  Return it as a list of
-    lines usable for inserting into a docutils ViewList (used as argument
-    of nested_parse().)  An empty line is added to act as a separator between
-    this docstring and following content.
-    """
-    lines = s.expandtabs().splitlines()
-    # Find minimum indentation of any non-blank lines after first line.
-    margin = sys.maxint
-    for line in lines[1:]:
-        content = len(line.lstrip())
-        if content:
-            indent = len(line) - content
-            margin = min(margin, indent)
-    # Remove indentation.
-    if lines:
-        lines[0] = lines[0].lstrip()
-    if margin < sys.maxint:
-        for i in range(1, len(lines)): lines[i] = lines[i][margin:]
-    # Remove any leading blank lines.
-    while lines and not lines[0]:
-        lines.pop(0)
-    # make sure there is an empty line at the end
-    if lines and lines[-1]:
-        lines.append('')
-    return lines
-
-
 def get_module_charset(module):
     """Return the charset of the given module (cached in _module_charsets)."""
     if module in _module_charsets:
diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py
index f4bd1b1d..e52a231d 100644
--- a/sphinx/pycode/__init__.py
+++ b/sphinx/pycode/__init__.py
@@ -10,11 +10,11 @@
 """
 
 import sys
-import time
 from os import path
 
 from sphinx.pycode import pytree
 from sphinx.pycode.pgen2 import driver, token, parse, literals
+from sphinx.util.docstrings import prepare_docstring, prepare_commentdoc
 
 
 # load the Python grammar
@@ -31,47 +31,6 @@ number2name = pygrammar.number2symbol.copy()
 number2name.update(token.tok_name)
 
 
-def prepare_commentdoc(s):
-    """
-    Extract documentation comment lines (starting with #:) and return them as a
-    list of lines.  Returns an empty list if there is no documentation.
-    """
-    result = []
-    lines = [line.strip() for line in s.expandtabs().splitlines()]
-    for line in lines:
-        if line.startswith('#: '):
-            result.append(line[3:])
-    if result and result[-1]:
-        result.append('')
-    return result
-
-
-def prepare_literaldoc(s):
-    # first, "evaluate" the string
-    s = literals.evalString(s)
-    # then, prepare (XXX copied from ext/autodoc)
-    lines = s.expandtabs().splitlines()
-    # Find minimum indentation of any non-blank lines after first line.
-    margin = sys.maxint
-    for line in lines[1:]:
-        content = len(line.lstrip())
-        if content:
-            indent = len(line) - content
-            margin = min(margin, indent)
-    # Remove indentation.
-    if lines:
-        lines[0] = lines[0].lstrip()
-    if margin < sys.maxint:
-        for i in range(1, len(lines)): lines[i] = lines[i][margin:]
-    # Remove any leading blank lines.
-    while lines and not lines[0]:
-        lines.pop(0)
-    # make sure there is an empty line at the end
-    if lines and lines[-1]:
-        lines.append('')
-    return lines
-
-
 _eq = pytree.Leaf(token.EQUAL, '=')
 
 
@@ -122,7 +81,8 @@ class AttrDocVisitor(pytree.NodeVisitor):
             return
         if prev.type == sym.simple_stmt and \
                prev[0].type == sym.expr_stmt and _eq in prev[0].children:
-            docstring = prepare_literaldoc(node[0].value)
+            # need to "eval" the string because it's returned in its original form
+            docstring = prepare_docstring(literals.evalString(node[0].value))
             self.add_docstring(prev[0], docstring)
 
     def visit_funcdef(self, node):
@@ -215,9 +175,10 @@ class ModuleAnalyzer(object):
 
 
 if __name__ == '__main__':
+    import time
     x0 = time.time()
-    #ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', 'sphinx.builders.html')
-    ma = ModuleAnalyzer.for_file(__file__.rstrip('c'), 'sphinx.builders.html')
+    ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', 'sphinx.builders.html')
+    #ma = ModuleAnalyzer.for_file(__file__.rstrip('c'), 'sphinx.builders.html')
     x1 = time.time()
     for (ns, name), doc in ma.find_attr_docs().iteritems():
         print '>>', ns, name
diff --git a/sphinx/util/docstrings.py b/sphinx/util/docstrings.py
new file mode 100644
index 00000000..d7e20e4c
--- /dev/null
+++ b/sphinx/util/docstrings.py
@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.util.docstrings
+    ~~~~~~~~~~~~~~~~~~~~~~
+
+    Utilities for docstring processing.
+
+    :copyright: 2008 by Georg Brandl.
+    :license: BSD, see LICENSE for details.
+"""
+
+import sys
+
+
+def prepare_docstring(s):
+    """
+    Convert a docstring into lines of parseable reST.  Return it as a list of
+    lines usable for inserting into a docutils ViewList (used as argument
+    of nested_parse().)  An empty line is added to act as a separator between
+    this docstring and following content.
+    """
+    lines = s.expandtabs().splitlines()
+    # Find minimum indentation of any non-blank lines after first line.
+    margin = sys.maxint
+    for line in lines[1:]:
+        content = len(line.lstrip())
+        if content:
+            indent = len(line) - content
+            margin = min(margin, indent)
+    # Remove indentation.
+    if lines:
+        lines[0] = lines[0].lstrip()
+    if margin < sys.maxint:
+        for i in range(1, len(lines)): lines[i] = lines[i][margin:]
+    # Remove any leading blank lines.
+    while lines and not lines[0]:
+        lines.pop(0)
+    # make sure there is an empty line at the end
+    if lines and lines[-1]:
+        lines.append('')
+    return lines
+
+
+def prepare_commentdoc(s):
+    """
+    Extract documentation comment lines (starting with #:) and return them as a
+    list of lines.  Returns an empty list if there is no documentation.
+    """
+    result = []
+    lines = [line.strip() for line in s.expandtabs().splitlines()]
+    for line in lines:
+        if line.startswith('#: '):
+            result.append(line[3:])
+    if result and result[-1]:
+        result.append('')
+    return result