<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, May 10, 2016 at 8:12 AM, Julien Danjou <span dir="ltr"><<a href="mailto:julien@danjou.info" target="_blank">julien@danjou.info</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><span class="">On Tue, May 10 2016, Anne Gentle wrote:<br>
<br>
> Ceilometer -- sorry, Julien, I hadn't reached out individually to you.<br>
> Could you let me know your plans for the RST API reference docs?<br>
<br>
</span>For Gnocchi and Aodh, we want to move to whatever the new format is and<br>
build a reference description in our tree (so we can maintain and update<br>
it as we go). I heard Swagger is the way to go, so that's we're going to<br>
look into – unless someone redirects us.<br></blockquote><div><br></div><div>I won't redirect you, just guide. :) To get Swagger to build to HTML you'll need something like this patch we experimented with in api-site: <a href="https://review.openstack.org/#/c/286659/">https://review.openstack.org/#/c/286659/</a> Or, simply provide the Swagger files and let users do with them as they want. See our talk at the Summit for some ideas: <a href="https://www.openstack.org/videos/video/openapi-as-a-standard-a-new-way-forward-for-api-documentation-design-and-tool">https://www.openstack.org/videos/video/openapi-as-a-standard-a-new-way-forward-for-api-documentation-design-and-tool</a></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">
<br>
For examples of usage of our APIs, we have a documentation built<br>
dynamically within the documentation for Gnocchi (see<br>
<a href="http://gnocchi.xyz/rest.html" rel="noreferrer" target="_blank">http://gnocchi.xyz/rest.html</a>). Real HTTP calls are being made to<br>
generate that documentation, so no replies are hand written. That makes<br>
us sure that the documentation is always up-to-date.<br>
We may want to also implement that in Aodh at some point.<br>
<br>
For Ceilometer, I don't think we want to put much effort in it. The v2<br>
API is being deprecated and slowly moved out of our way. The /v2/events<br>
API is being moved in a 4th project, named Panko, that will follow<br>
Gnocchi & Aodh in term of documentation.<br></blockquote><div><br></div><div>It's a small set of files: <a href="https://github.com/openstack/api-site/tree/master/api-ref/source/telemetry/v2">https://github.com/openstack/api-site/tree/master/api-ref/source/telemetry/v2</a> How about I ask someone to do the conversion and add it to <a href="https://github.com/openstack/ceilometer">https://github.com/openstack/ceilometer</a>? I have someone in mind who's looking for a task. Let me know and I'll get her started.</div><div><br></div><div>Thanks,</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">
<br>
I hope that'll clarify things!<br>
<br>
Cheers,<br>
<span class=""><font color="#888888">--<br>
Julien Danjou<br>
;; Free Software hacker<br>
;; <a href="https://julien.danjou.info" rel="noreferrer" target="_blank">https://julien.danjou.info</a><br>
</font></span></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div>Anne Gentle</div><div><a href="http://www.justwriteclick.com" style="font-size:12.8px" target="_blank">www.justwriteclick.com</a><br></div></div></div></div></div>
</div></div>