Move docstring processing to an util module.

1 files changed, 56 insertions, 0 deletions

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