From d186b998a216b37a424e9ce6ad6dd8789c013cf2 Mon Sep 17 00:00:00 2001
From: Andrey Kurilin <akurilin@mirantis.com>
Date: Wed, 24 Feb 2016 16:45:03 +0200
Subject: [PATCH] [Docs] Rework "Rally Plugins Reference"

- Add "Contents" add the top of page
- Mark each group of plugin as a Category and make it's name as a link
- Mark each plugin as a Sub-category and make it's name as a link
- Parse plugin description and parameters instead of displaying them as quotes
- Add pluging's namespaces
- Add references to github for each plugin module
- Add "Table Of Contents" sidebar(already used at readthedocs, but was missed
  from http://docs.openstack.org/developer/rally/)

Change-Id: I8889ccc7f82b0f46495ce607c242d37242360a25
---
 doc/ext/plugin_reference.py            | 61 ++++++++++++++------------
 doc/source/conf.py                     |  2 +-
 doc/source/plugin/plugin_reference.rst |  3 ++
 3 files changed, 36 insertions(+), 30 deletions(-)

diff --git a/doc/ext/plugin_reference.py b/doc/ext/plugin_reference.py
index 5342d2b458..b7fa7f67db 100644
--- a/doc/ext/plugin_reference.py
+++ b/doc/ext/plugin_reference.py
@@ -13,12 +13,12 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-from docutils import nodes
 from docutils.parsers import rst
 
 from oslo_utils import importutils
 
 from rally import plugins
+from utils import category, subcategory, paragraph, parse_text
 
 DATA = [
     {
@@ -72,49 +72,52 @@ def _make_pretty_parameters(parameters):
     if not parameters:
         return ""
 
-    result = "PARAMETERS:\n"
+    result = "**Parameters**:\n\n"
     for p in parameters:
         result += "* %(name)s: %(doc)s\n" % p
     return result
 
 
-def _get_plugin_info(plugin_group_item):
-    module, cls = plugin_group_item["base"].split(":")
-    plugin_base = getattr(importutils.import_module(module), cls)
+def make_plugin_section(plugin, base_name):
+    subcategory_obj = subcategory("%s [%s]" % (plugin.get_name(), base_name))
+    info = plugin.get_info()
+    if info["title"]:
+        subcategory_obj.append(paragraph(info["title"]))
 
-    def process_plugin(p):
-        info = p.get_info()
+    if info["description"]:
+        subcategory_obj.extend(parse_text(info["description"]))
 
-        description = [info["title"] or ""]
-        if info["description"]:
-            description.append(info["description"])
-        if info["parameters"]:
-            description.append(_make_pretty_parameters(info["parameters"]))
+    if info["namespace"]:
+        subcategory_obj.append(paragraph(
+                "**Namespace**: %s" % info["namespace"]))
+
+    if info["parameters"]:
+        subcategory_obj.extend(parse_text(
+                _make_pretty_parameters(info["parameters"])))
         if info["returns"]:
-            description.append("RETURNS:\n%s" % info["returns"])
-        description.append("MODULE:\n%s" % info["module"])
-
-        return {
-            "name": p.get_name(),
-            "description": "\n\n".join(description)
-        }
-
-    return map(process_plugin, plugin_base.get_all())
+            subcategory_obj.extend(parse_text(
+                    "**Returns**:\n%s" % info["returns"]))
+    filename = info["module"].replace(".", "/")
+    ref = "https://github.com/openstack/rally/blob/master/%s.py" % filename
+    subcategory_obj.extend(parse_text("**Module**:\n`%s`__\n\n__ %s"
+                                      % (info["module"], ref)))
+    return subcategory_obj
 
 
-def make_plugin_section(plugin_group):
+def make_plugin_base_section(plugin_group):
     elements = []
 
     for item in plugin_group["items"]:
         name = item["name"].title() if "SLA" != item["name"] else item["name"]
-        elements.append(nodes.subtitle(
-            text="%ss [%s]" % (name, plugin_group["group"])))
+        category_obj = category("%s %ss" % (plugin_group["group"].title(),
+                                            name))
+        elements.append(category_obj)
 
-        for p in _get_plugin_info(item):
-            elements.append(nodes.rubric(
-                text="%s [%s]" % (p["name"], item["name"])))
+        module, cls = item["base"].split(":")
+        plugin_base = getattr(importutils.import_module(module), cls)
 
-            elements.append(nodes.doctest_block(text=p["description"]))
+        for p in plugin_base.get_all():
+            category_obj.append(make_plugin_section(p, item["name"]))
 
     return elements
 
@@ -124,7 +127,7 @@ class PluginReferenceDirective(rst.Directive):
     def run(self):
         content = []
         for i in range(len(DATA)):
-            content.extend(make_plugin_section(DATA[i]))
+            content.extend(make_plugin_base_section(DATA[i]))
 
         return content
 
diff --git a/doc/source/conf.py b/doc/source/conf.py
index fbbb302c24..36ee54933b 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -165,7 +165,7 @@ html_last_updated_fmt = subprocess.Popen(git_cmd,
 html_use_smartypants = False
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+html_sidebars = {'**': ['searchbox.html', 'globaltoc.html']}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
diff --git a/doc/source/plugin/plugin_reference.rst b/doc/source/plugin/plugin_reference.rst
index ee370b1d19..3c6a050b1f 100644
--- a/doc/source/plugin/plugin_reference.rst
+++ b/doc/source/plugin/plugin_reference.rst
@@ -1,7 +1,10 @@
+:tocdepth: 1
 .. _plugin_reference:
 
 
 Rally Plugins Reference
 =======================
 
+.. contents:: :depth: 2
+
 .. generate_plugin_reference::