<div dir="ltr">(Sorry accidentally omitted the mailing list when replying to the thread previously)<br><div><div><div><br><div class="gmail_quote">---------- Forwarded message ----------<br>From: <b class="gmail_sendername">Christopher Yeoh</b> <span dir="ltr"><<a href="mailto:cbkyeoh@gmail.com">cbkyeoh@gmail.com</a>></span><br>
Date: Sun, Jul 7, 2013 at 9:45 AM<br>Subject: Re: [Openstack-docs] Doc'ing Nova V3 API<br>To: Nicholas Chase <<a href="mailto:nchase@mirantis.com">nchase@mirantis.com</a>><br><br><br><div dir="ltr"><div class="gmail_extra">
<br><div class="gmail_quote"><div class="im">On Sat, Jul 6, 2013 at 11:03 PM, 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>


<br></blockquote><div><br></div></div><div>Ideally this is what I'd like to see. There is no intention to go back and change things for the V2 API, but for V3 I want to make things as automatable as possible and we have the opportunity to do things differently than we do for V2 if it will make the process easier. <br>

<br>Is it possible to get to the state where you could just run a script that points at the nova doc tree and automatically produces the required files with no further intervention required except a commit?<br></div><div class="im">
<div>
 </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
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></blockquote><div><br></div></div><div>So I think we can produce something like this, but is that all that is required? Is there enough to tie together this sort of index file with the corresponding JSON/XML  (say based on filenames?). Also, do we need to worry about internationalisation here?<br>

</div><div> </div>Chris<br></div></div></div>
</div><br></div></div></div></div>