From e8b8aedc9c002b261ade03fc0f50dcb7a33862d5 Mon Sep 17 00:00:00 2001
From: Boris Pavlovic <boris@pavlovic.me>
Date: Tue, 22 Sep 2015 02:01:05 -0700
Subject: [PATCH] [docs] Imporve Plugin Reference

Tables with plugins looks quite ugly so this patch removes tables
and use just rubrics and doctest_block types of nodes

Change-Id: Ifb5d53cfa1d86ab477671d3485d63fbf09f9246c
---
 doc/ext/plugin_reference.py | 75 +++++++++++--------------------------
 1 file changed, 22 insertions(+), 53 deletions(-)

diff --git a/doc/ext/plugin_reference.py b/doc/ext/plugin_reference.py
index f6345730..054e7642 100644
--- a/doc/ext/plugin_reference.py
+++ b/doc/ext/plugin_reference.py
@@ -22,35 +22,35 @@ from rally import plugins
 
 DATA = [
     {
-        "group": "Task plugins",
+        "group": "task",
         "items": [
             {
-                "name": "Scenario Runners",
+                "name": "scenario runner",
                 "base": "rally.task.runner:ScenarioRunner"
             },
             {
-                "name": "SLAs",
+                "name": "SLA",
                 "base": "rally.task.sla:SLA"
             },
             {
-                "name": "Contexts",
+                "name": "context",
                 "base": "rally.task.context:Context"
             },
             {
-                "name": "Scenarios",
+                "name": "scenario",
                 "base": "rally.task.scenario:Scenario"
             }
         ]
     },
     {
-        "group": "Deployment plugins",
+        "group": "deployment",
         "items": [
             {
-                "name": "Engines",
+                "name": "engine",
                 "base": "rally.deployment.engine:Engine"
             },
             {
-                "name": "ProviderFactory",
+                "name": "server provider",
                 "base":
                 "rally.deployment.serverprovider.provider:ProviderFactory"
             }
@@ -59,38 +59,6 @@ DATA = [
 ]
 
 
-def make_row(data):
-    row = nodes.row()
-    for item in data:
-        node_type, text = item
-        entry = nodes.entry()
-        entry.append(node_type(text=text))
-        row.append(entry)
-
-    return row
-
-
-def make_table(data):
-    table = nodes.table()
-    table_group = nodes.tgroup()
-
-    for w in data["colwidth"]:
-        table_group.append(nodes.colspec(colwidth=w))
-
-    table_head = nodes.thead()
-    table_head.append(make_row(data["headers"]))
-    table_group.append(table_head)
-
-    table_body = nodes.tbody()
-    for row in data["rows"]:
-        table_body.append(make_row(row))
-    table_group.append(table_body)
-
-    table.append(table_group)
-
-    return table
-
-
 def _make_pretty_parameters(parameters):
     if not parameters:
         return ""
@@ -117,25 +85,27 @@ def _get_plugin_info(plugin_group_item):
             description.append("RETURNS:\n%s" % info["returns"])
         description.append("MODULE:\n%s" % info["module"])
 
-        return [
-            [nodes.inline, p.get_name()],
-            [nodes.doctest_block, "\n\n".join(description)]
-        ]
+        return {
+            "name": p.get_name(),
+            "description": "\n\n".join(description)
+        }
 
-    return {
-        "headers": zip([nodes.inline] * 2,
-                       ["name", "description"]),
-        "colwidth": [1, 1],
-        "rows": map(process_plugin, plugin_base.get_all())
-    }
+    return map(process_plugin, plugin_base.get_all())
 
 
 def make_plugin_section(plugin_group):
     elements = []
 
     for item in plugin_group["items"]:
-        elements.append(nodes.rubric(text=item["name"]))
-        elements.append(make_table(_get_plugin_info(item)))
+        name = item["name"].title() if "SLA" != item["name"] else item["name"]
+        elements.append(nodes.subtitle(
+            text="%ss [%s]" % (name, plugin_group["group"])))
+
+        for p in _get_plugin_info(item):
+            elements.append(nodes.rubric(
+                text="%s [%s]" % (p["name"], item["name"])))
+
+            elements.append(nodes.doctest_block(text=p["description"]))
 
     return elements
 
@@ -145,7 +115,6 @@ class PluginReferenceDirective(rst.Directive):
     def run(self):
         content = []
         for i in range(len(DATA)):
-            content.append(nodes.subtitle(text=DATA[i]["group"]))
             content.extend(make_plugin_section(DATA[i]))
 
         return content