document actions in the REST api document

they were documented in the raml, but not converted to rst
buildbot · Sep 26, 2016 · a493f8c · a493f8c
1 parent 45b3d5a
commit a493f8c
Show file tree

Hide file tree

Showing 5 changed files with 46 additions and 7 deletions.
diff --git a/master/buildbot/test/unit/test_util_raml.py b/master/buildbot/test/unit/test_util_raml.py
@@ -76,3 +76,8 @@ def test_endpoints_by_type(self):
         self.assertIn(
             "/masters/{masterid}/builders/{builderid}/workers/{workerid}",
             self.api.endpoints_by_type['worker'].keys())
+
+    def test_iter_actions(self):
+        build = self.api.endpoints_by_type['build']
+        actions = dict(self.api.iter_actions(build['/builds/{buildid}']))
+        self.assertEqual(sorted(actions.keys()), sorted(['rebuild', 'stop']))
diff --git a/master/buildbot/util/raml.py b/master/buildbot/util/raml.py
@@ -78,3 +78,13 @@ def format_json(self, j, indent):
     def parse_types(self):
         types = self.api['types']
         return types
+
+    def iter_actions(self, endpoint):
+        ACTIONS_MAGIC = '/actions/'
+        for k, v in endpoint.iteritems():
+            if k.startswith(ACTIONS_MAGIC):
+                k = k[len(ACTIONS_MAGIC):]
+                v = v['post']
+                # simplify the raml tree for easier processing
+                v['body'] = v['body']['application/json'].get('properties', {})
+                yield (k, v)
diff --git a/master/docs/bbdocs/ext.py b/master/docs/bbdocs/ext.py
@@ -270,6 +270,17 @@ class BBDomain(Domain):
                                                           names=('pathkey',), typenames=('type',),
                                                           can_collapse=True),
                                            ]),
+        'raction': make_ref_target_directive('raction',
+                                           indextemplates=[
+                                               'single: Resource Action; %s',
+                                           ],
+                                           name_annotation='POST with method:',
+                                           has_content=True,
+                                           doc_field_types=[
+                                               TypedField('body', label='Body keys',
+                                                          names=('body',), typenames=('type',),
+                                                          can_collapse=True),
+                                           ]),
     }
 
     roles = {
@@ -301,8 +312,9 @@ class BBDomain(Domain):
         make_index("cmdline", "Command Line Index"),
         make_index("msg", "MQ Routing Key Index"),
         make_index("event", "Data API Event Index"),
-        make_index("rtype", "Data API Resource Type Index"),
-        make_index("rpath", "Data API Path Index"),
+        make_index("rtype", "REST/Data API Resource Type Index"),
+        make_index("rpath", "REST/Data API Path Index"),
+        make_index("raction", "REST/Data API Actions Index"),
     ]
 
     def resolve_xref(self, env, fromdocname, builder, typ, target, node,

diff --git a/master/docs/developer/rest.rst b/master/docs/developer/rest.rst
@@ -211,7 +211,7 @@ RAML describes and documents all our data, rest, and javascript APIs in a format
 
     {{type.description}}
     {% endif %}
-    {% if name in raml.endpoints_by_type -%}
+    {% if name in raml.endpoints_by_type -%}{# if type has endpoints #}
     Endpoints
     ---------
     {% for ep, config in raml.endpoints_by_type[name].items()|sort -%}
@@ -230,7 +230,18 @@ RAML describes and documents all our data, rest, and javascript APIs in a format
             :bb:rtype:`collection` of :bb:rtype:`{{method_ep['eptype']}}`
         {% endif %}
 
-    {% endif %}
-    {% endfor %}
-    {% endif %}
-    {% endfor %}
+    {% endif %}{# if ep has get #}
+
+    {% for method, action in raml.iter_actions(config) -%}
+    .. bb:raction:: {{ep}}:{{method}}
+
+        :body string method:  must be ``{{ method }}``
+
+        {% for key, value in action['body'].items() -%}
+        :body {{value.type}} {{key}}: {{raml.reindent(value.description, 4*2)}}
+        {% endfor %}
+
+    {% endfor %}{# endpoints #}
+    {% endfor %}{# endpoints #}
+    {% endif %}{# if type has endpoints #}
+    {% endfor %}{# for each types #}
diff --git a/master/docs/indices.rst b/master/docs/indices.rst
@@ -12,5 +12,6 @@ Indices and Tables
 * :bb:index:`event`
 * :bb:index:`rtype`
 * :bb:index:`rpath`
+* :bb:index:`raction`
 * :ref:`modindex`
 * :ref:`search`