<div dir="ltr">Hi Nick,<br><div class="gmail_extra"><br><br><div class="gmail_quote">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 class="im">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 style>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> </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 style>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 style><br></div><div style>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
----  Nick<div class="HOEnZb"><div class="h5"><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><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>