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: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
