[openstack-dev] [all] summit session recap - getting API Docs off WADL and into RST

Anne Gentle annegentle at justwriteclick.com
Tue May 10 13:02:43 UTC 2016

All docs are migrated off of WADL now, but not all are publishing. Please
see https://wiki.openstack.org/wiki/Documentation/Migrate#API_Reference_Plan
and my post that high-fived with Sean's just minutes ago for the latest


On Tue, May 10, 2016 at 7:21 AM, Sean Dague <sean at dague.net> wrote:

> Part of the cross project session track -
> https://etherpad.openstack.org/p/newton-api-docs-rst
> The first half of the session was spent going over the background issues
> and the work so far. The TL;DR
> * We need to get off WADL, it's a dead spec, and it's use is inhibiting
> contributions
> * We *need* to get up to date docs to our users, ASAP. The API
> References are way out of data and inaccurate in most places (and
> missing entirely for 50% of our projects with REST APIs)
> * Swagger (OpenAPI) was looked at, but there are hard problems in our
> legacy APIs that aren't possible to solve within the spec at hand
> * Nova team started building some semistructured tooling based on RST /
> Sphinx to move forward.
> We then looked at the sphinx extension work in the Nova api-ref tree.
> Question: why not https://pythonhosted.org/sphinxcontrib-httpdomain/?
> Answer: we have some specific needs on formating, headers where it
> doesn't fit (see etherpad for full answer).
> Next Steps:
> * Nova team is doing a doc sprint to try to get through verification of
> the content we've got
> * Once that is done (under control) sdague to work on splitting out
> sphinx extension into a dedicated project to make it easy for others to
> consume / contribute
> * Cinder, Ironic, and Keystone ready to get started on similar conversion
> --
> Sean Dague
> http://dague.net
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Anne Gentle
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160510/a1520675/attachment.html>

More information about the OpenStack-dev mailing list