openstack/rally-openstack
Code Issues Proposed changes

[docs] Improve plugins and cli references

Browse Source 
* 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
This commit is contained in:
Andrey Kurilin 2017-02-01 14:26:19 +02:00 committed by Andrey Kurilin
parent c1a2628501
commit 648e4698ed
2 changed files with 29 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
doc/ext/plugin_reference.py
View File

@ -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"

12
doc/ext/utils.py
View File

@ -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