Open Stack

Hi OpenStack docs aficionados - I wanted to make sure you all know the
latest with the API "specs" migrations. Here's what I sent to 20+ PTLs
today.

-----

Hi all y'all PTLs:

tl;dr: Please approve my upcoming patch to your <project>-specs repo to get
the API "spec" into your repo. Voice concerns here and now.

Many of the API reference documents were meant for the contributor
developer to know what was going into an API. So, the history of that
document was forged as a specification. As projects beyond swift and nova
were added, projects made similar documents. They're output to HTML at
http://docs.openstack.org/api/api-specs.html. However, as we now have a
<project>-specs repo, it makes sense to move to those repos. In that move,
also it makes sense to migrate to RST rather than DocBook/WADL. We'll
continue with WADL to build the long API reference listing until a suitable
replacement can be found. I'm hoping for the Swagger 2.0 specification to
meet our needs, then I'll work on a migration plan for the reference
information. This plan is scoped just for the "longer-form" API
specification. I'll write a similar email to the openstack-dev list once
you all clear the plan for takeoff. If you have concerns, let me know by
Friday 8/22.

The Juno projects where this document needs to migrate to a specification
are:
nova (compute-api) v2, v3
swift (object-api) v1
glance (image-api) v1, v1.1, v2
keystone (identity-api) v2.0, v3
neutron (netconn-api) v1.0, v2.0
cinder (volume-api) v1.0, v2.0

Juno projects that have this type of document in a separate <service>-api
repo are:
trove (trove)

Juno projects that do not provide this type of prose-based spec for their
API are:
ceilometer
heat
sahara

Incubating projects, this information is just a heads-up so you know how
we're thinking about API documentation going forward.
ironic
zaqar (marconi)
barbican
designate

I'm going to do the migration work with pandoc and propose the patch to the
project's repo. Be on the lookout for those patches. Please let me know if
you see issues with this plan -- so far everyone has been very excited to
welcome their RST documentation overlords for API prose.

Thanks,
Anne
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140820/1c58e512/attachment-0001.html>