Open Stack

On 11/28/2013 09:33 PM, Anne Gentle wrote:
> On Thu, Nov 28, 2013 at 1:51 PM, Nicholas Chase<nchase at mirantis.com>  wrote:
>
>> I have a little reservation about generating one project differently than
>> the others, from a maintainability perspective.  Not that I'm against
>> automating the documentation, but would it maybe make sense to have the
>> script generate the WADL instead of the docs?  This way if we make changes
>> to the docs themselves we don't have to change the Ceilometer script,
>> because the docs will still be getting the WADL they expect.
>>
>> ----  Nick
>>
>>
> Hi Nick, We recognize that desire for consistency, but this is the type of
> automation we'd like other projects to adopt. This etherpad shows how far
> apart we are across all the projects in API doc consitency. [1] I'd like
> other projects to follow this lead, but know full well that's not
> necessarily going to work for all APIs, especially those with extensions
> that are larger than this API.
>
> Cyril, I think you would build the WADL with the Sphinx extension as a
> Jenkins job, triggered when the Ceilometer gets an update. Then automate
> the patch proposal to the api-site similar to how translation jobs work. A
> human can then review the api-site patch (also similar to how translation
> jobs work). I'd rather not automate beyond creating the patch as we still
> want to review wording, meaning, and so on. I'd also like for Diane to take
> a look when she gets back from this week off.
>

I'd be willing to either do everything automatically (pushing directly 
to api.openstack.org, as Julien suggested) or do as you say, but without 
automatically submitting a patch. As a developer, I do not want "git 
log" to show me a bunch of "Update of Ceilometer documentation by a 
robot" commit logs that will be meaningless. Both options would be fine.


> Thanks for getting it this far - I know you had a lot of steps to cover!
>

My pleasure.

> Also, one recent addition you'd want to know about is that Andreas is
> starting a new repo to hold doc utilities and tools -- this one might be a
> candidate for inclusion there.
>

I'll have to take a look at it.

> Also, are you generating docbook in addition to wadl or just wadl? I see
> the code in stackforge has a lot of docbook naming but I don't know if it's
> really generating docbook.
>

I'm just generating WADL. The thing is, I'm not familiar with 
Docbook/WADL/etc. - I think of the files I generate as 'XML' - so I 
wrote "docbook" everywhere :/

> Also, does your tool work only with JSON sample requests and responses or
> XML requests and responses also?

It currently adds JSON/XML responses samples. So, if a method returns a 
list of 'Alarms', the documentation includes an example of that, in both 
JSON and XML. This part of the code has not been pushed to stackforge 
yet: I'm waiting to see if the code I generated is good 
(https://review.openstack.org/#/c/57342/) before pushing it.

Thanks for your comments !
Cyril.