add rawraml display

master/buildbot/util/raml.py

@@ -38,8 +38,11 @@ def __init__(self):
         # waiting for raml1.0 support in ramlfications
         # we cannot use its raml parser
         # so we just use its loader
-        self.api = ramlfications.load(os.path.join(
-            os.path.dirname(__file__), os.pardir, 'spec', 'api.raml'))
+        fn = os.path.join(os.path.dirname(__file__), os.pardir, 'spec', 'api.raml')
+        self.api = ramlfications.load(fn)
+        with open(fn) as f:
+            self.rawraml = f.read()
+
         endpoints = {}
         self.endpoints_by_type = {}
         self.endpoints = self.parse_endpoints(endpoints, "", self.api)

master/docs/developer/rest.rst

@@ -244,3 +244,30 @@ RAML describes and documents all our data, rest, and javascript APIs in a format
     {% endfor %}{# endpoints #}
     {% endif %}{# if type has endpoints #}
     {% endfor %}{# for each types #}
+
+    Raw endpoints
+    .............
+
+    Raw endpoints allow to download content in their raw format (i.e. not within a json glue).
+    The ``content-disposition`` http header is set, so that the browser knows which file to store the content to.
+
+    {% for ep, config in raml.rawendpoints.items()|sort %}
+
+    .. bb:rpath:: {{ep}}
+
+        {% for key, value in config.uriParameters.items() -%}
+            :pathkey {{value.type}} {{key}}: {{raml.reindent(value.description, 4*2)}}
+        {% endfor %}
+
+    {{config['get'].description}}
+
+    {% endfor %}
+
+    Raml spec verbatim
+    ..................
+
+    Sometimes raml is just clearer than formatted text.
+
+    .. code-block:: yaml
+
+        {{raml.reindent(raml.rawraml, 4*1)}}