Open Stack

Thanks for the summary Tom.


On Sun, Jul 7, 2013 at 5:59 PM, Tom Fifield <tom at openstack.org> wrote:

> Sorry all - this accidentally dropped off the list for a few replies
> before we realised.
>
> Here's the summary:
> Nick asked:
>
> I was suggesting that the nova code should generate the WADL when it
> generates the sample files.  That is, or is not, what happens now?
>
> Anne replied:
>
> The items that are auto-generated are the requests and responses in JSON
> and XML. The WADL is hand written to point to those generated files.
>
> Nick asked:
>
> can we have that same process also generate the WADL?  And would it solve
> the problem of missing pieces?
>
> Anne replied:
>
> We can ask if the validating step can generate docs also. That would be a
> good step towards completeness of the API doc.
>
> On this basis, I have created a new blueprint:
>
> https://blueprints.launchpad.**net/openstack-manuals/+spec/**
> autogenerate-api-reference<https://blueprints.launchpad.net/openstack-manuals/+spec/autogenerate-api-reference>
>
> to track the investigation
>
>
I don't think we need a blueprint just to investigate, do you? And the
blueprint would live in another project I suppose?

I also want to note that the QA list is having a similar discussion about
test artifacts and docs. [1] and Sean Dague is just kind of tired of the
lack of coordination across 9 APIs... probably not summarizing it well
enough, but that's kind of how I'm feeling too, that we could try to get
one project in line and then 8 others would have to buy into the approach.
We have to serve users first and foremost, so for me, I'd prefer to stay in
the land of user docs and not encroach into writing specs. Thoughts on
toeing that line or drawing it?

Anne


1. http://lists.openstack.org/pipermail/openstack-qa/2013-July/000599.html


> Regards,
>
> Tom
>
>
>
> On 08/07/13 04:48, Anne Gentle wrote:
>
>>
>>
>> Anne Gentle
>> Content Stacker
>> anne at openstack.org <mailto:anne at openstack.org>
>>
>>
>>
>> On Jul 7, 2013, at 2:19 PM, Nick Chase <nchase at mirantis.com
>> <mailto:nchase at mirantis.com>> wrote:
>>
>>  Right, ok, so what I'm saying is, can we have that same process also
>>> generate the WADL?  And would it solve the problem of missing pieces?
>>>
>>>
>>>
>> As far as I can tell no one has asked about docs until now. So we can
>> ask if the validating step can generate docs also. That would be a good
>> step towards completeness of the API doc.
>>
>>  On Sun, Jul 7, 2013 at 2:12 PM, Anne Gentle
>>> <annegentle at justwriteclick.com <mailto:annegentle@**justwriteclick.com<annegentle at justwriteclick.com>
>>> >>
>>>
>>> wrote:
>>>
>>>
>>>
>>>     Anne Gentle
>>>     Content Stacker
>>>     anne at openstack.org <mailto:anne at openstack.org>
>>>
>>>
>>>
>>>     On Jul 7, 2013, at 1:56 PM, Nick Chase <nchase at mirantis.com
>>>     <mailto:nchase at mirantis.com>> wrote:
>>>
>>>
>>>>
>>>>
>>>>     On Sat, Jul 6, 2013 at 7:39 PM, Tom Fifield <tom at openstack.org
>>>>     <mailto:tom at openstack.org>> wrote:
>>>>
>>>>
>>>>         However, in this case, since we're publishing the definitive
>>>>         reference
>>>>         on something that can actually be tested to be complete - we
>>>>         should have
>>>>         higher standards. Right now, the truth is, we have no idea
>>>>         how complete
>>>>         the API reference is. The only way we have to find out is to
>>>>         sit down
>>>>         with a beverage of some description and methodically work
>>>>         through a ton
>>>>         of code and a ton of WADL.
>>>>
>>>>
>>>>     OK, this is where I got confused; I was suggesting that the nova
>>>>     code
>>>>     should generate the WADL when it generates the sample files.
>>>>      That is,
>>>>     or is not, what happens now?
>>>>
>>>>
>>>     The items that are auto-generated are the requests and responses
>>>     in JSON and XML. The WADL is hand written to point to those
>>>     generated files.
>>>
>>>      ----  Nick
>>>>
>>>
>>>
>>>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130708/04c625e7/attachment.html>