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