Open Stack

On Sat, Jul 6, 2013 at 10:06 AM, Anne Gentle
<annegentle at justwriteclick.com>wrote:

> Hi Nick,
>
>
> On Sat, Jul 6, 2013 at 8:03 AM, 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?
>>
>
> 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.
>
>
>>
>> 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>
>>
>> or somesuch.
>>
>> We can then automagically include BOTH files.
>>
>>
> 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?
>
> Anne
>
>

Oops! just saw this!  Sorry for my absence these weeks (a thick mix of work
deadlines and exams kept me quite busy).

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.

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 :")

I'll be still busy next week, but pingable ;)

Laura
(ladquin)


 ----  Nick
>>
>>
>> ______________________________**_________________
>> Openstack-docs mailing list
>> Openstack-docs at lists.**openstack.org <Openstack-docs at lists.openstack.org>
>> http://lists.openstack.org/**cgi-bin/mailman/listinfo/**openstack-docs<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>
>>
>
>
>
> --
> Anne Gentle
> annegentle at justwriteclick.com
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130712/15b87d74/attachment-0001.html>