[openstack-dev] [infra] API docs latest-n-greatest

Anne Gentle annegentle at justwriteclick.com
Fri Aug 21 01:48:51 UTC 2015


Hi all,
A couple of notes for API docs this week. One is, the spec to enable RST
builds to developer.openstack.org/api-guide/<service> merged. The plan is
completely documented here:
http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html

I'm trying to work through the best way to build those while still working
with Russell Sim on the WADL to Swagger converter at fairy-slipper:
https://github.com/russell/fairy-slipper

Basically run migrate.sh and then run_server.sh to see what Swagger can
look like when published (very rough). I'm fixing errors found in the WADL
with migrate.sh as we go and hopefully we can start maintaining Swagger
only before October.
He's working on Issues #4 and #10 but all others are up for grabs:
https://github.com/russell/fairy-slipper/issues

Then, next release we can use our baseline Swagger to ensure the docs get
updated either automatically or manually. If your project already uses
Pecan you may be able to write Swagger with this
https://github.com/elmiko/pecan-swagger.

Some have noted these aren't in the OpenStack git namespace but right now,
the publishing outcome is more important than the governance so we'll get
there when needed.

I'll also put in a formal request here for the infrastructure team to let
us know how to request a server that can serve content on
developer.openstack.org rather than Cloud Sites. I'll attend the Infra team
meeting next week and I've added it to the agenda.
https://wiki.openstack.org/wiki/Meetings/InfraTeamMeeting#Agenda_for_next_meeting

Final note, I've written a set of API docs guidelines in the API Working
Group repository. Please review and offer input, since this guidance
applies for all OpenStack APIs. https://review.openstack.org/#/c/214817/

In summary:
 - Please keep the WADL updated for now and continue to fix WADL bugs.
 - Take a look at fairy-slipper for the migration and pecan-swagger for
generation.
 - Review the API docs guidelines and ask questions.
 - With less than 2 months until release, let's git 'er done.

Thanks,
Anne

-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150820/7df4f5d4/attachment.html>


More information about the OpenStack-dev mailing list