Open Stack

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.

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

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.

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.

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

1. https://etherpad.openstack.org/p/icehouse-api-doc-repos


>
> On 11/28/2013 2:41 PM, Cyril Roelandt wrote:
>
>> Hello !
>>
>> I recently wrote a Sphinx extension
>> (https://github.com/stackforge/sphinxcontrib-docbookrestapi) that is
>> used to generate the Ceilometer documentation for api.openstack.org
>> (http://api.openstack.org/api-ref-metering.html). It should be
>> integrated into Ceilometer soon enough
>> (https://review.openstack.org/#/c/57978/ and
>> https://review.openstack.org/#/c/57574/).
>>
>> Julien Danjou (CCed) proposed that we automatically generate this
>> documentation. The idea would be to remove the WADL file from api-site,
>> and replace it with a script that periodically checks out Ceilometer,
>> runs the documentation generator, then pushes the generated files to
>> api.openstack.org.
>>
>> Would you agree on making such a change ? If so, do you know how it
>> could be done technically (which machine should run the script, for
>> instance) ?
>>
>>
>> Best regards,
>> Cyril Roelandt.
>>
>> _______________________________________________
>> Openstack-docs mailing list
>> Openstack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
>>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



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