Open Stack

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 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 site?
You might know that the developer.openstack.org site documents over
900GET/PUT/POST/DELETE/PATCH calls for a dozen OpenStack services already
on the 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.

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160112/0d2dcbaf/attachment-0001.html>