Open Stack

Anne, thank you for this update. And thank you to the contributors who 
improved the SDK and developer guide documentation. Fantastic work, all 
of you!

Best,
-jay

On 01/13/2016 12:18 AM, Anne Gentle wrote:
> Hi all,
> I wanted to be sure to post to the dev, docs, and user mailing lists
> about the progress towards supporting application devs using OpenStack
> REST APIs. We discussed at the cross-project meeting today and you can
> read more details in the meeting log. [1]
>
> This blog post [2] explains what's happening this month with a migration
> as well as build jobs that enable project teams to write tutorials and
> how-to guides.
>
> This Thursday afternoon/ early Friday morning, the new fairy-slipper
> core team [3] is meeting in Google Hangout to get to put faces to names.
> Feel free to join us if you're interested!
>
> I'll be reaching out to the API working group liaisons [4] to be sure
> you all are up-to-date and can take any next actions you need to. You're
> always welcome to attend the doc team meeting which has a standing item
> about API doc and design.
>
> Thanks to everyone who got us this far -- Russell Sim and Karen Bradshaw
> especially! Also, thanks to the API working group and the nova API
> specialty team for poking at the early work and being willing to carry
> the torch. And of course, Diane Fleming's work accounts for over 60% of
> all patches for the http://developer.openstack.org site, her volume and
> quality of work is wonderful. Thanks to Tom Fifield for connecting the
> dots and the peeps.
>
> I also want to emphasize that over 120 individual contributors kept the
> API reference info updated in the last release, and that long tail of
> contributions is what's keeping this valuable info accurate and trusted.
> Thanks to every one of you.
> Anne
>
> 1.
> http://eavesdrop.openstack.org/meetings/crossproject/2016/crossproject.2016-01-12-21.02.log.html
> 2.
> http://www.openstack.org/blog/2016/01/whats-next-for-application-developer-guides/.
>
> 3. https://review.openstack.org/#/admin/groups/1240,members
> 4. http://specs.openstack.org/openstack/api-wg/liaisons.html
>
> The full blog post is pasted below, for those who don't like to
> clickety-click-click too much. :)
> What's new for application developer guides?
> Summary
> This month, the developer.openstack.org <http://developer.openstack.org>
> site gets a new look and changes its source tooling. Read on for details
> about how these changes affect your project team.
>
> Why are we changing the developer.openstack.org
> <http://developer.openstack.org> site?
> You might know that the developer.openstack.org
> <http://developer.openstack.org> site documents over
> 900GET/PUT/POST/DELETE/PATCH calls for a dozen OpenStack services
> already on the developer.openstack.org <http://developer.openstack.org>
> site. As a couple of the keynote speakers in Tokyo so elegantly put it,
> the trustworthiness and consistency of the OpenStack APIs influenced
> their decision to run their business workloads in an OpenStack cloud.
>
> Those interfaces need docs, lots of docs, and not only reference docs.
> While it takes a huge effort to maintain accurate references, we also
> need to document API usage and scenarios.
>
> Now that we’ve written both an API Guide and a “Writing your first
> OpenStack application” tutorial, we want the site to be the go-to
> location for app devs, product developers, and anyone who needs to
> unlock the power of their OpenStack infrastructure.
>
> In this release, the docs’ platform introduces tooling that lets you
> migrate from WADL to Swagger and integrate RST-sourced documentation
> with the API reference documentation. The “why” analysis is clear: we
> must community-source this info and make it easy to maintain and update
> so that users can trust it enough to bet their workloads on it.
>
> Later on, this post answers the “how” questions.
>
> Why all these changes at this point in the release?
> Well, we haven’t had to release the API documentation like we release
> services documentation. We have done a lot of maintenance on the site,
> with bug fixing and so on. But it’s time to take the leap. Last release
> we made a proof-of-concept. This release we unleash a solution that
> helps us make incremental progress toward our goals.
>
> How do you keep your API docs updated after January 16th?
> On January 16th, we’ll migrate the Images API WADL and DocBook files to
> Swagger and RST files. Then we’ll test the build process and the content
> itself to validate the migration.
>
> After testing, we will migrate the files for these services:
>
> Identity
> Compute
> Images
> Networks
> Block Storage
> Object Storage
>
> Then, the remaining services can migrate their files by using the
> validated tooling.
>
> If you do provide an OpenStack API service, read on.
>
> For the nova project, place your how-to and conceptual articles in the
> api-guide folder in the nova repository. Other projects can mimic these
> patches that created an api-guide and build jobs for the Compute
> api-guide. You continue to update reference information in the
> openstack/api-site repo. However, the source files have changed.
>
> With this release, you can embed annotations in your source code if you
> want to generate the reference information. Here’s an example patch from
> the nova project. Because we haven’t had a project do this yet
> completely, the build jobs still need to be written.
>
> If your project already has WADL files, they will be migrated to Swagger
> files and stored in the api-site repository. The WADL files will be
> deleted; you can retrieve them from Git.
>
> If your project does not have a WADL file, then you write Swagger plus
> RST to document your API calls, parameters, and reference information.
> You can generate Swagger from annotations or create Swagger from scratch
> that you store in the api-site repository. You should review, store, and
> build RST for conceptual or how-to information from within your project
> team’s repository.
>
> All projects should use this set of API documentation guidelines from
> the OpenStack API working group any time their service has a REST API.
> This document tells you what and how much to write. If you follow the
> suggested outline, your API guide will be accurate and complete.
>
> After the source files and build jobs exist, the docs are built to
> developer.openstack.org <http://developer.openstack.org>.
>
> Where can I get help for my project’s API Guides?
>
> These specifications describe the details: Application Developer Guides
> and Rework API Reference Information.
>
> You can ask questions in #openstack-sdks or #openstack-docs on IRC. We
> await those magical API docs fairies who grant wishes, but in the
> meantime but we can point you in the right direction and give you the
> tools for your quest.
>
> What if I still have questions?
>
> Contact me, Anne Gentle, by email or IRC and I’ll get back to you as
> soon as possible.
>
> I’m eager to enable our audience with great user-centric docs and hope
> that you’ll join us as we fulfill the vision.--
> Anne Gentle
> Rackspace
> Principal Engineer
> www.justwriteclick.com <http://www.justwriteclick.com>
>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>