<div dir="ltr">Thanks for the summary Tom.<br><div class="gmail_extra"><br><br><div class="gmail_quote">On Sun, Jul 7, 2013 at 5:59 PM, Tom Fifield <span dir="ltr"><<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Sorry all - this accidentally dropped off the list for a few replies before we realised.<br>
<br>
Here's the summary:<br>
Nick asked:<div class="im"><br>
I was suggesting that the nova code should generate the WADL when it generates the sample files. That is, or is not, what happens now?<br>
<br></div>
Anne replied:<div class="im"><br>
The items that are auto-generated are the requests and responses in JSON and XML. The WADL is hand written to point to those generated files.<br>
<br></div>
Nick asked:<div class="im"><br>
can we have that same process also generate the WADL? And would it solve the problem of missing pieces?<br>
<br></div>
Anne replied:<div class="im"><br>
We can ask if the validating step can generate docs also. That would be a good step towards completeness of the API doc.<br>
<br></div>
On this basis, I have created a new blueprint:<br>
<br>
<a href="https://blueprints.launchpad.net/openstack-manuals/+spec/autogenerate-api-reference" target="_blank">https://blueprints.launchpad.<u></u>net/openstack-manuals/+spec/<u></u>autogenerate-api-reference</a><br>
<br>
to track the investigation<br>
<br></blockquote><div><br></div><div style>I don't think we need a blueprint just to investigate, do you? And the blueprint would live in another project I suppose? </div><div style><br></div><div style>I also want to note that the QA list is having a similar discussion about test artifacts and docs. [1] and Sean Dague is just kind of tired of the lack of coordination across 9 APIs... probably not summarizing it well enough, but that's kind of how I'm feeling too, that we could try to get one project in line and then 8 others would have to buy into the approach. We have to serve users first and foremost, so for me, I'd prefer to stay in the land of user docs and not encroach into writing specs. Thoughts on toeing that line or drawing it?</div>
<div style><br></div><div style>Anne</div><div> </div><div><br></div><div>1. <a href="http://lists.openstack.org/pipermail/openstack-qa/2013-July/000599.html">http://lists.openstack.org/pipermail/openstack-qa/2013-July/000599.html</a></div>
<div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
Regards,<br>
<br>
Tom<div class="im"><br>
<br>
<br>
On 08/07/13 04:48, Anne Gentle wrote:<br>
</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
<br>
Anne Gentle<br>
Content Stacker<br>
<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a> <mailto:<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>><div class="im"><br>
<br>
<br>
On Jul 7, 2013, at 2:19 PM, Nick Chase <<a href="mailto:nchase@mirantis.com" target="_blank">nchase@mirantis.com</a><br></div><div class="im">
<mailto:<a href="mailto:nchase@mirantis.com" target="_blank">nchase@mirantis.com</a>>> wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Right, ok, so what I'm saying is, can we have that same process also<br>
generate the WADL? And would it solve the problem of missing pieces?<br>
<br>
<br>
</blockquote>
<br>
As far as I can tell no one has asked about docs until now. So we can<br>
ask if the validating step can generate docs also. That would be a good<br>
step towards completeness of the API doc.<br>
<br>
</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class="im">
On Sun, Jul 7, 2013 at 2:12 PM, Anne Gentle<br></div>
<<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a> <mailto:<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@<u></u>justwriteclick.com</a>>><div class="im">
<br>
wrote:<br>
<br>
<br>
<br>
Anne Gentle<br>
Content Stacker<br></div>
<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a> <mailto:<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>><div class="im"><br>
<br>
<br>
On Jul 7, 2013, at 1:56 PM, Nick Chase <<a href="mailto:nchase@mirantis.com" target="_blank">nchase@mirantis.com</a><br></div>
<mailto:<a href="mailto:nchase@mirantis.com" target="_blank">nchase@mirantis.com</a>>> wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class="im">
<br>
<br>
<br>
On Sat, Jul 6, 2013 at 7:39 PM, Tom Fifield <<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a><br></div><div class="im">
<mailto:<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a>>> wrote:<br>
<br>
<br>
However, in this case, since we're publishing the definitive<br>
reference<br>
on something that can actually be tested to be complete - we<br>
should have<br>
higher standards. Right now, the truth is, we have no idea<br>
how complete<br>
the API reference is. The only way we have to find out is to<br>
sit down<br>
with a beverage of some description and methodically work<br>
through a ton<br>
of code and a ton of WADL.<br>
<br>
<br>
OK, this is where I got confused; I was suggesting that the nova<br>
code<br>
should generate the WADL when it generates the sample files.<br>
That is,<br>
or is not, what happens now?<br>
<br>
</div></blockquote><div class="im">
<br>
The items that are auto-generated are the requests and responses<br>
in JSON and XML. The WADL is hand written to point to those<br>
generated files.<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
---- Nick<br>
</blockquote>
<br>
<br>
</div></blockquote></blockquote>
<br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</div></div>