<div dir="ltr">All docs are migrated off of WADL now, but not all are publishing. Please see <a href="https://wiki.openstack.org/wiki/Documentation/Migrate#API_Reference_Plan">https://wiki.openstack.org/wiki/Documentation/Migrate#API_Reference_Plan</a> and my post that high-fived with Sean's just minutes ago for the latest status.<div><br></div><div><a href="http://lists.openstack.org/pipermail/openstack-dev/2016-May/094478.html">http://lists.openstack.org/pipermail/openstack-dev/2016-May/094478.html</a><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, May 10, 2016 at 7:21 AM, Sean Dague <span dir="ltr"><<a href="mailto:sean@dague.net" target="_blank">sean@dague.net</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Part of the cross project session track -<br>
<a href="https://etherpad.openstack.org/p/newton-api-docs-rst" rel="noreferrer" target="_blank">https://etherpad.openstack.org/p/newton-api-docs-rst</a><br>
<br>
The first half of the session was spent going over the background issues<br>
and the work so far. The TL;DR<br>
<br>
* We need to get off WADL, it's a dead spec, and it's use is inhibiting<br>
contributions<br>
* We *need* to get up to date docs to our users, ASAP. The API<br>
References are way out of data and inaccurate in most places (and<br>
missing entirely for 50% of our projects with REST APIs)<br>
* Swagger (OpenAPI) was looked at, but there are hard problems in our<br>
legacy APIs that aren't possible to solve within the spec at hand<br>
* Nova team started building some semistructured tooling based on RST /<br>
Sphinx to move forward.<br>
<br>
We then looked at the sphinx extension work in the Nova api-ref tree.<br>
<br>
Question: why not <a href="https://pythonhosted.org/sphinxcontrib-httpdomain/" rel="noreferrer" target="_blank">https://pythonhosted.org/sphinxcontrib-httpdomain/</a>?<br>
Answer: we have some specific needs on formating, headers where it<br>
doesn't fit (see etherpad for full answer).<br>
<br>
Next Steps:<br>
<br>
* Nova team is doing a doc sprint to try to get through verification of<br>
the content we've got<br>
* Once that is done (under control) sdague to work on splitting out<br>
sphinx extension into a dedicated project to make it easy for others to<br>
consume / contribute<br>
* Cinder, Ironic, and Keystone ready to get started on similar conversion<br>
<span class="HOEnZb"><font color="#888888"><br>
--<br>
Sean Dague<br>
<a href="http://dague.net" rel="noreferrer" target="_blank">http://dague.net</a><br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</font></span></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div>Anne Gentle</div><div><a href="http://www.justwriteclick.com" style="font-size:12.8px" target="_blank">www.justwriteclick.com</a><br></div></div></div></div></div>
</div>