<br><br><div class="gmail_quote">On Sat, Jul 6, 2013 at 10:06 AM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">Hi Nick,<br><div class="gmail_extra"><br><br><div class="gmail_quote"><div class="im">On Sat, Jul 6, 2013 at 8:03 AM, Nicholas Chase <span dir="ltr"><<a href="mailto:nchase@mirantis.com" target="_blank">nchase@mirantis.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div>On 7/6/2013 6:41 AM, Tom Fifield wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
As such, I'd like to start a discussion about our methodology for<br>
producing the API reference document, and possible ways we can improve<br>
it, potentially remove some of the manual steps, and integrate some of<br>
the changes nova has made in its sample file generation.<br>
</blockquote>
<br></div>
I'm admittedly new to this, so if I've got it wrong, please go easy on me. :)<br>
<br>
If we created a standard "format" for each entry, what are the chances that we could simply let nova generate bits and pieces of the doc itself the same way it generates sample files, then knit them together?<br>
</blockquote><div><br></div></div><div>This is what the site does now. WADL is the format for each entry, then the Maven plugin generates the bits and pieces of the doc and outputs the HTML. </div><div class="im"><div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
In other words, in addition to generating, say, os-quota-sets-defaults.json (making that up) with the JSON response, it could generate os-quota-sets-defaults.txt, with:<br>
<br>
<table><br>
<row><entry>tenant_id</entry><<u></u>entry>The ID for the tenant or account in a multi-tenancy cloud.</entry></row><br>
<row><entry>tenant_id</entry><<u></u>entry>The ID for the tenant or account to act on.</entry></row><br>
</table><br>
<br>
or somesuch.<br>
<br>
We can then automagically include BOTH files.<br>
<br></blockquote><div><br></div></div><div>I think a great next step is some automation for nova codebase to automagically put the sample JSON and XML response and request where the docs can build from. Laura Alves had a pretty good start on that, what does it look like now Laura?</div>
<div><br></div><div>Anne</div><div class="im"><div> </div></div></div></div></div></blockquote><div><br>Oops! just saw this! Sorry for my absence these weeks (a thick mix of work deadlines and exams kept me quite busy).<br>
<br>I never abandoned the idea of reaching some level of automation for the wadl and sample generation (along with some modification to the API ref page), but it hasn't unfortunately advanced at all beyond some comments in the -infra list.<br>
<br>I won't go too far here, but as Anne mentioned in the last message, much of it is closely related to being able to work on the dev repos, or at least reach some kind of agreement with the coding crowd (I think I added some ideas to the etherpad used informally in the summit). I think there are some discussions right now about that I couldn't properly follow, so I'll catch up with that before blurting nonsense :")<br>
<br>I'll be still busy next week, but pingable ;)<br><br>Laura<br>(ladquin)<br><br><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra">
<div class="gmail_quote"><div class="im"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
---- Nick<div><div><br>
<br>
______________________________<u></u>_________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.<u></u>openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-docs</a><br>
</div></div></blockquote></div></div><span class="HOEnZb"><font color="#888888"><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</font></span></div></div>
<br>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br>