[docs] Check docstrings of plugin bases
We are using docstings of plugin bases while publishing docs, so it is important to ensure that all of them provides valid rst Change-Id: I0bee6942c3058d6c936c5ccdbf798b3960e63242
This commit is contained in:
parent
3a64909311
commit
0281b6c000
@ -172,6 +172,7 @@ class BaseContext(plugin.Plugin, functional.FunctionalMixin,
|
||||
@validation.add_default("jsonschema")
|
||||
@plugin.base()
|
||||
class Context(BaseContext, validation.ValidatablePluginMixin):
|
||||
"""The base class for task contexts."""
|
||||
def __init__(self, ctx):
|
||||
super(Context, self).__init__(ctx)
|
||||
self.task = self.context.get("task", {})
|
||||
|
@ -64,10 +64,12 @@ class TaskExporter(plugin.Plugin, validation.ValidatablePluginMixin):
|
||||
different formats and send them to the different systems.
|
||||
|
||||
To discover available plugins, call
|
||||
``rally plugin list --plugin-base TaskExporter``.
|
||||
|
||||
rally plugin list --plugin-base TaskExporter.
|
||||
|
||||
To export results of a task, call
|
||||
``rally task export --uuid <task-uuid> --type <plugin-name> --to <dest>``
|
||||
|
||||
rally task export --uuid <task-uuid> --type <plugin-name> --to <dest>
|
||||
|
||||
"""
|
||||
|
||||
|
@ -93,6 +93,7 @@ def preprocess(name, context, args):
|
||||
@plugin.base()
|
||||
@six.add_metaclass(abc.ABCMeta)
|
||||
class ResourceType(plugin.Plugin):
|
||||
"""A helper plugin for pre-processing input data of resources."""
|
||||
|
||||
def __init__(self, context, cache=None):
|
||||
self._context = context
|
||||
|
@ -63,9 +63,8 @@ class DocstringsTestCase(test.TestCase):
|
||||
# the list with plugins names which use rst definitions in their docstrings
|
||||
_HAS_VALID_DEFINITIONS = []
|
||||
|
||||
def _validate_rst(self, plugin_name, text, msg_buffer):
|
||||
parsed_docstring = _parse_rst(text)
|
||||
for item in parsed_docstring:
|
||||
def _iterate_parsed_rst(self, plugin_name, items, msg_buffer):
|
||||
for item in items:
|
||||
if (isinstance(item, nodes.definition_list)
|
||||
and plugin_name not in self._HAS_VALID_DEFINITIONS):
|
||||
msg_buffer.append("Plugin %s has a docstring with invalid "
|
||||
@ -76,6 +75,9 @@ class DocstringsTestCase(test.TestCase):
|
||||
msg_buffer.append(
|
||||
"A warning is caught while parsing docstring of '%s' "
|
||||
"plugin: %s" % (plugin_name, item.astext()))
|
||||
elif item.children:
|
||||
self._iterate_parsed_rst(plugin_name, item.children,
|
||||
msg_buffer)
|
||||
|
||||
def _check_docstrings(self, msg_buffer):
|
||||
for plg_cls in plugin.Plugin.get_all():
|
||||
@ -99,9 +101,10 @@ class DocstringsTestCase(test.TestCase):
|
||||
# "definitions" means that there is an issue with intends or
|
||||
# missed empty line before the list title and list items.
|
||||
if doc_info["description"]:
|
||||
self._validate_rst(plg_cls.get_name(),
|
||||
doc_info["description"],
|
||||
msg_buffer)
|
||||
parsed_docstring = _parse_rst(doc_info["description"])
|
||||
self._iterate_parsed_rst(plg_cls.get_name(),
|
||||
parsed_docstring,
|
||||
msg_buffer)
|
||||
|
||||
def _check_described_params(self, msg_buffer):
|
||||
for plg_cls in plugin.Plugin.get_all():
|
||||
@ -123,3 +126,24 @@ class DocstringsTestCase(test.TestCase):
|
||||
self._check_described_params(msg_buffer)
|
||||
if msg_buffer:
|
||||
self.fail("\n%s" % "\n===============\n".join(msg_buffer))
|
||||
|
||||
def test_plugin_bases_have_docstrigs(self):
|
||||
plugin_bases = set()
|
||||
msg_buffer = []
|
||||
for plg_cls in plugin.Plugin.get_all(allow_hidden=True):
|
||||
plugin_bases.add(plg_cls._get_base())
|
||||
for base in plugin_bases:
|
||||
name = "%s.%s" % (base.__module__, base.__name__)
|
||||
try:
|
||||
docstring = base._get_doc()
|
||||
except Exception:
|
||||
docstring = base.__doc__
|
||||
|
||||
print(name)
|
||||
parsed_docstring = _parse_rst(docstring)
|
||||
self._iterate_parsed_rst(name,
|
||||
parsed_docstring,
|
||||
msg_buffer)
|
||||
|
||||
if msg_buffer:
|
||||
self.fail("\n%s" % "\n===============\n".join(msg_buffer))
|
||||
|
Loading…
Reference in New Issue
Block a user