From 1cafda8e691195c4bc2432c847fc44936aa02ad4 Mon Sep 17 00:00:00 2001
From: Andrey Kurilin <andr.kurilin@gmail.com>
Date: Wed, 1 Feb 2017 14:26:19 +0200
Subject: [PATCH] [docs] Improve plugins and cli references

* re-use ``make_definition`` function for displaying parameters of plugins.
  Profit: unified view; references to each argument of each plugin.
* Use list in ``make_definition`` function
* fix indention of plugins parameters descriptions

Change-Id: I0b7e567134d36abde313d5538eab99b282f60178
---
 doc/ext/plugin_reference.py           | 29 +++++++++++++++++++--------
 doc/ext/utils.py                      | 12 +++++++----
 rally/common/plugin/info.py           |  3 ++-
 tests/unit/common/plugin/test_info.py |  6 +++---
 4 files changed, 34 insertions(+), 16 deletions(-)

diff --git a/doc/ext/plugin_reference.py b/doc/ext/plugin_reference.py
index 6575da8c8a..67610039d6 100644
--- a/doc/ext/plugin_reference.py
+++ b/doc/ext/plugin_reference.py
@@ -19,7 +19,8 @@ import re
 from rally.common.plugin import discover
 from rally.common.plugin import plugin
 from rally import plugins
-from utils import category, subcategory, section, paragraph, parse_text
+from utils import category, subcategory, section, paragraph, parse_text, \
+    make_definition
 
 
 CATEGORIES = {
@@ -41,14 +42,19 @@ class PluginsReferenceDirective(rst.Directive):
     option_spec = {"base_cls": str}
 
     @staticmethod
-    def _make_pretty_parameters(parameters):
+    def _make_pretty_parameters(parameters, ref_prefix):
         if not parameters:
-            return ""
+            return []
 
-        result = "**Parameters**:\n\n"
+        results = [paragraph("**Parameters**:")]
         for p in parameters:
-            result += "* %(name)s: %(doc)s\n" % p
-        return result
+            pname = p["name"]
+            ref = ("%s%s" % (ref_prefix, pname)).lower().replace(".", "-")
+            if "type" in p:
+                pname += " (%s)" % p["type"]
+            pdoc = "\n  ".join(p["doc"].split("\n"))
+            results.extend(make_definition(pname, ref, [pdoc]))
+        return results
 
     def _make_plugin_section(self, plugin_cls, base_name=None):
         section_name = plugin_cls.get_name()
@@ -68,11 +74,18 @@ class PluginsReferenceDirective(rst.Directive):
                 "**Namespace**: %s" % info["namespace"]))
 
         if info["parameters"]:
-            section_obj.extend(parse_text(
-                self._make_pretty_parameters(info["parameters"])))
+            if base_name:
+                ref_prefix = "%s-%s-" % (base_name, plugin_cls.get_name())
+            else:
+                ref_prefix = "%s-" % plugin_cls.get_name()
+
+            section_obj.extend(self._make_pretty_parameters(info["parameters"],
+                                                            ref_prefix))
+
             if info["returns"]:
                 section_obj.extend(parse_text(
                     "**Returns**:\n%s" % info["returns"]))
+
         filename = info["module"].replace(".", "/")
         ref = "https://github.com/openstack/rally/blob/master/%s.py" % filename
         section_obj.extend(parse_text("**Module**:\n`%s`__\n\n__ %s"
diff --git a/doc/ext/utils.py b/doc/ext/utils.py
index 4abb26270e..2bd53782d3 100644
--- a/doc/ext/utils.py
+++ b/doc/ext/utils.py
@@ -20,6 +20,7 @@ from docutils import frontend
 from docutils import nodes
 from docutils import utils
 from docutils.parsers import rst
+import string
 
 import six
 
@@ -44,10 +45,13 @@ def make_definition(term, ref, descriptions):
     """Constructs definition with reference to it"""
     ref = ref.replace("_", "-").replace(" ", "-")
     definition = parse_text(
-            ".. _%(ref)s:\n\n*%(term)s* (ref__)\n\n__ #%(ref)s" %
+            ".. _%(ref)s:\n\n* *%(term)s* [ref__]\n\n__ #%(ref)s" %
             {"ref": ref, "term": term})
     for descr in descriptions:
-        if isinstance(descr, (six.text_type, six.binary_type)):
-            descr = paragraph("  %s" % descr)
-        definition.append(descr)
+        if descr:
+            if isinstance(descr, (six.text_type, six.binary_type)):
+                if descr[0] not in string.ascii_uppercase:
+                    descr = descr.capitalize()
+                descr = paragraph("  %s" % descr)
+            definition.append(descr)
     return definition
diff --git a/rally/common/plugin/info.py b/rally/common/plugin/info.py
index f788930c24..2e2e0fd690 100644
--- a/rally/common/plugin/info.py
+++ b/rally/common/plugin/info.py
@@ -62,7 +62,8 @@ def parse_docstring(docstring):
 
             if params_returns_desc:
                 params = [
-                    {"name": name, "doc": doc}
+                    {"name": name,
+                     "doc": "\n".join(docstrings.prepare_docstring(doc))}
                     for name, doc in PARAM_REGEX.findall(params_returns_desc)
                 ]
 
diff --git a/tests/unit/common/plugin/test_info.py b/tests/unit/common/plugin/test_info.py
index 68abf8bf1d..f2d7efd080 100644
--- a/tests/unit/common/plugin/test_info.py
+++ b/tests/unit/common/plugin/test_info.py
@@ -37,7 +37,7 @@ description.
             "short_description": "One-line description.",
             "long_description": "Multi-\nline-\ndescription.",
             "params": [{"name": "p1", "doc": "Param 1 description.\n"},
-                       {"name": "p2", "doc": "Param 2\n           "
+                       {"name": "p2", "doc": "Param 2\n"
                                              "description.\n"}],
             "returns": "Return value\ndescription."
         }
@@ -55,8 +55,8 @@ description.
             "short_description": "One-line description.",
             "long_description": "",
             "params": [{"name": "p1", "doc": "Param 1 description.\n"},
-                       {"name": "p2", "doc": "Param 2\n           "
-                                             "description."}],
+                       {"name": "p2", "doc": "Param 2\n"
+                                             "description.\n"}],
             "returns": ""
         }
         self.assertEqual(expected, info.parse_docstring(docstring))