Open Stack

On Tue, May 10, 2016 at 8:12 AM, Julien Danjou <julien at danjou.info> wrote:

> On Tue, May 10 2016, Anne Gentle wrote:
>
> > Ceilometer -- sorry, Julien, I hadn't reached out individually to you.
> > Could you let me know your plans for the RST API reference docs?
>
> For Gnocchi and Aodh, we want to move to whatever the new format is and
> build a reference description in our tree (so we can maintain and update
> it as we go). I heard Swagger is the way to go, so that's we're going to
> look into – unless someone redirects us.
>

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:
https://review.openstack.org/#/c/286659/ Or, simply provide the Swagger
files and let users do with them as they want. See our talk at the Summit
for some ideas:
https://www.openstack.org/videos/video/openapi-as-a-standard-a-new-way-forward-for-api-documentation-design-and-tool


>
> For examples of usage of our APIs, we have a documentation built
> dynamically within the documentation for Gnocchi (see
> http://gnocchi.xyz/rest.html). Real HTTP calls are being made to
> generate that documentation, so no replies are hand written. That makes
> us sure that the documentation is always up-to-date.
> We may want to also implement that in Aodh at some point.
>
> For Ceilometer, I don't think we want to put much effort in it. The v2
> API is being deprecated and slowly moved out of our way. The /v2/events
> API is being moved in a 4th project, named Panko, that will follow
> Gnocchi & Aodh in term of documentation.
>

It's a small set of files:
https://github.com/openstack/api-site/tree/master/api-ref/source/telemetry/v2
How about I ask someone to do the conversion and add it to
https://github.com/openstack/ceilometer? I have someone in mind who's
looking for a task. Let me know and I'll get her started.

Thanks,
Anne


>
> I hope that'll clarify things!
>
> Cheers,
> --
> Julien Danjou
> ;; Free Software hacker
> ;; https://julien.danjou.info
>



-- 
Anne Gentle
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160510/25e4ddf4/attachment.html>