Open Stack

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