openstack/rally-openstack
Code Issues Proposed changes

Merge "[docs] Improve plugins and cli references"

Browse Source
This commit is contained in:
Jenkins 2017-02-03 19:43:18 +00:00 committed by Gerrit Code Review
commit 2293fb00d9
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 discover
from rally.common.plugin import plugin from rally.common.plugin import plugin
from rally import plugins 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 = { CATEGORIES = {
@ -41,14 +42,19 @@ class PluginsReferenceDirective(rst.Directive):
option_spec = {"base_cls": str} option_spec = {"base_cls": str}
@staticmethod @staticmethod
def _make_pretty_parameters(parameters): def _make_pretty_parameters(parameters, ref_prefix):
if not parameters: if not parameters:
return "" return []
result = "**Parameters**:\n\n" results = [paragraph("**Parameters**:")]
for p in parameters: for p in parameters:
result += "* %(name)s: %(doc)s\n" % p pname = p["name"]
return result 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): def _make_plugin_section(self, plugin_cls, base_name=None):
section_name = plugin_cls.get_name() section_name = plugin_cls.get_name()
@ -68,11 +74,18 @@ class PluginsReferenceDirective(rst.Directive):
"**Namespace**: %s" % info["namespace"])) "**Namespace**: %s" % info["namespace"]))
if info["parameters"]: if info["parameters"]:
section_obj.extend(parse_text( if base_name:
self._make_pretty_parameters(info["parameters"]))) 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"]: if info["returns"]:
section_obj.extend(parse_text( section_obj.extend(parse_text(
"**Returns**:\n%s" % info["returns"])) "**Returns**:\n%s" % info["returns"]))
filename = info["module"].replace(".", "/") filename = info["module"].replace(".", "/")
ref = "https://github.com/openstack/rally/blob/master/%s.py" % filename ref = "https://github.com/openstack/rally/blob/master/%s.py" % filename
section_obj.extend(parse_text("**Module**:\n`%s`__\n\n__ %s" section_obj.extend(parse_text("**Module**:\n`%s`__\n\n__ %s"

6
doc/ext/utils.py
View File

@ -20,6 +20,7 @@ from docutils import frontend
from docutils import nodes from docutils import nodes
from docutils import utils from docutils import utils
from docutils.parsers import rst from docutils.parsers import rst
import string
import six import six
@ -44,10 +45,13 @@ def make_definition(term, ref, descriptions):
"""Constructs definition with reference to it""" """Constructs definition with reference to it"""
ref = ref.replace("_", "-").replace(" ", "-") ref = ref.replace("_", "-").replace(" ", "-")
definition = parse_text( 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}) {"ref": ref, "term": term})
for descr in descriptions: for descr in descriptions:
if descr:
if isinstance(descr, (six.text_type, six.binary_type)): if isinstance(descr, (six.text_type, six.binary_type)):
if descr[0] not in string.ascii_uppercase:
descr = descr.capitalize()
descr = paragraph(" %s" % descr) descr = paragraph(" %s" % descr)
definition.append(descr) definition.append(descr)
return definition return definition