remove runtime dep on sphinx

in rally/common/plugin/info replace sphinx prepare_docstring
with trim function from PEP-257 reference implementation

Also move Sphinx from requirements to test-requirements
Added several unittests for PEP-257 trim function

Change-Id: I9f13906cbb3ea9212a78b5bed178e15780001caf

rally/common/plugin/info.py

@@ -14,8 +14,7 @@
 #    under the License.
 
 import re
-
-from sphinx.util import docstrings
+import sys
 
 PARAM_OR_RETURNS_REGEX = re.compile(":(?:param|returns)")
 RETURNS_REGEX = re.compile(":returns: (?P<doc>.*)", re.S)
@@ -23,6 +22,40 @@ PARAM_REGEX = re.compile(":param (?P<name>[\*\w]+): (?P<doc>.*?)"
                          "(?:(?=:param)|(?=:return)|(?=:raises)|\Z)", re.S)
 
 
+def trim(docstring):
+    """trim function from PEP-257"""
+    if not docstring:
+        return ""
+    # Convert tabs to spaces (following the normal Python rules)
+    # and split into a list of lines:
+    lines = docstring.expandtabs().splitlines()
+    # Determine minimum indentation (first line doesn't count):
+    indent = sys.maxsize
+    for line in lines[1:]:
+        stripped = line.lstrip()
+        if stripped:
+            indent = min(indent, len(line) - len(stripped))
+    # Remove indentation (first line is special):
+    trimmed = [lines[0].strip()]
+    if indent < sys.maxsize:
+        for line in lines[1:]:
+            trimmed.append(line[indent:].rstrip())
+    # Strip off trailing and leading blank lines:
+    while trimmed and not trimmed[-1]:
+        trimmed.pop()
+    while trimmed and not trimmed[0]:
+        trimmed.pop(0)
+
+    # Current code/unittests expects a line return at
+    # end of multiline docstrings
+    # workaround expected behavior from unittests
+    if "\n" in docstring:
+        trimmed.append("")
+
+    # Return a single string:
+    return "\n".join(trimmed)
+
+
 def reindent(string):
     return "\n".join(l.strip() for l in string.strip().split("\n"))
 
@@ -43,7 +76,7 @@ def parse_docstring(docstring):
     params = []
 
     if docstring:
-        docstring = "\n".join(docstrings.prepare_docstring(docstring))
+        docstring = trim(docstring)
 
         lines = docstring.split("\n", 1)
         short_description = lines[0]
@@ -61,8 +94,7 @@ def parse_docstring(docstring):
 
             if params_returns_desc:
                 params = [
-                    {"name": name,
-                     "doc": "\n".join(docstrings.prepare_docstring(doc))}
+                    {"name": name, "doc": trim(doc)}
                     for name, doc in PARAM_REGEX.findall(params_returns_desc)
                 ]
 

requirements.txt

@@ -21,7 +21,6 @@ PyYAML>=3.10.0,<=3.12                                  # MIT
 python-subunit>=0.0.18,<=1.2.0
 requests>=2.14.2,<=2.18.1                              # Apache License, Version 2.0
 SQLAlchemy>=1.0.10,!=1.1.5,!=1.1.6,!=1.1.7,!=1.1.8,<=1.1.11  # MIT
-sphinx>=1.6.2,<=1.6.3                                  # BSD
 six>=1.9.0,<=1.10.0                                    # MIT
 virtualenv>=13.1.0,<=15.1.0                            # MIT
 

test-requirements.txt

@@ -18,6 +18,7 @@ mock>=2.0,<=2.0.0
 python-dateutil>=2.4.2,<=2.6.0                         # Simplified BSD
 testtools>=1.4.0,<=2.3.0
 
+sphinx>=1.6.2,<=1.6.3                                  # BSD
 oslosphinx>=4.7.0,<=4.15.0                             # Apache Software License
 oslotest>=1.10.0,<=2.16.0                              # Apache Software License
 

tests/unit/common/plugin/test_info.py

@@ -17,6 +17,50 @@ from rally.common.plugin import info
 from tests.unit import test
 
 
+class DocstringTestCasePep257(test.TestCase):
+    docstring_no_leading_whitespace = """One-line description.
+
+Multi-
+line-
+description.
+
+:param p1: Param 1 description.
+:param p2: Param 2
+           description.
+:returns: Return value
+          description.
+"""
+    docstring_indented = """One-line description.
+
+                       Multi-
+                       line-
+                       description.
+
+                       :param p1: Param 1 description.
+                       :param p2: Param 2
+                                  description.
+                       :returns: Return value
+                                 description.
+                       """
+
+    docstring_oneline = """Simple oneline description."""
+
+    def test_trim_docstring_multi_line_no_extra_whitespace(self):
+        docstring = self.docstring_no_leading_whitespace
+        expected = self.docstring_no_leading_whitespace
+        self.assertEqual(expected, info.trim(docstring))
+
+    def test_trim_docstring_trivial(self):
+        docstring = self.docstring_indented
+        expected = self.docstring_no_leading_whitespace
+        self.assertEqual(expected, info.trim(docstring))
+
+    def test_trim_docstring_oneline(self):
+        docstring = self.docstring_oneline
+        expected = self.docstring_oneline
+        self.assertEqual(expected, info.trim(docstring))
+
+
 class DocstringTestCase(test.TestCase):
 
     def test_parse_complete_docstring(self):