Open Stack

(Sorry accidentally omitted the mailing list when replying to the thread
previously)

---------- Forwarded message ----------
From: Christopher Yeoh <cbkyeoh at gmail.com>
Date: Sun, Jul 7, 2013 at 9:45 AM
Subject: Re: [Openstack-docs] Doc'ing Nova V3 API
To: Nicholas Chase <nchase at mirantis.com>



On Sat, Jul 6, 2013 at 11:03 PM, Nicholas Chase <nchase at mirantis.com> wrote:

> On 7/6/2013 6:41 AM, Tom Fifield wrote:
>
>> As such, I'd like to start a discussion about our methodology for
>> producing the API reference document, and possible ways we can improve
>> it, potentially remove some of the manual steps, and integrate some of
>> the changes nova has made in its sample file generation.
>>
>
> I'm admittedly new to this, so if I've got it wrong, please go easy on me.
> :)
>
> 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?
>
>
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.

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?


> 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:
>
> <table>
> <row><entry>tenant_id</entry><**entry>The ID for the tenant or account in
> a multi-tenancy cloud.</entry></row>
> <row><entry>tenant_id</entry><**entry>The ID for the tenant or account to
> act on.</entry></row>
> </table>
>
>
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?

Chris
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130707/5b23959a/attachment.html>