openstack team mailing list archive

[Jorge Williams <jorge.williams@xxxxxxxxxxxxx>]

Keystone is using it more than Nova, especially to document their extensions.  It's working with our existing docs tool chain.

You can reference a WADL directly from the DocBook source,  you can go in and reference particular resources and methods it will parse stuff out and put it in the right place.  For example in:

https://github.com/openstack/identity-api/blob/master/openstack-identity-api/src/docbkx/identity-service-api.xml

You see something like this:


<section xml:id="Tenant_Operations">
                <title>Tenant Operations</title>
                <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02";>
                        <wadl:resource href="identity-admin.wadl#tenants">
                                <wadl:method href="listTenants"/>
                                <wadl:method href="getTenantByName"/>
                        </wadl:resource>
                        <wadl:resource href="identity-admin.wadl#tenantById">
                                <wadl:method href="getTenantById"/>
                        </wadl:resource>
                        <wadl:resource href="identity-admin.wadl#userRolesForTenant">
                                <wadl:method href="listRolesForUserOnTenant"/>
                        </wadl:resource>
                </wadl:resources>
        </section>


And that's saying reach into the wadl identity-admin.wadl look  the resources and methods listed and generate the docs here.  That produces section 3.2.3 (http://docs.openstack.org/api/openstack-identity-service/2.0/content/Tenant_Operations.html) and all of the related subsections 3.2.3.1-3.2.3-4. For some reason the team has decided to put the WADL and Docbook in separate projects.  You can see the WADL that's being referred to here:

https://github.com/openstack/keystone/blob/master/keystone/content/admin/identity-admin.wadl

You can also embed WADL directly into the docbook instead of referencing it from a separate file. Additionally, you can process the WADL directly (this a new feature) and generate something like an appendix.  WADL isn't narrative, so the DocBook is there to glue the operations into a narrative form.

-jOrGe W.

On Oct 25, 2011, at 5:30 PM, Joseph Heck wrote:

Which dev docs and how? I haven't spotted those scripts or systems...

-joe

On Oct 25, 2011, at 2:58 PM, Jorge Williams wrote:

Some of that dev guide documentation is generated from a WADL :-)  The purpose of a WADL is that it is machine readable so it opens up a lot of possibilities, for creating docs, testing, validation, etc.

-jOrGe W.

On Oct 25, 2011, at 4:14 PM, Daryl Walleck wrote:

Hi everyone,

This is just my opinion, but I've only found WADLs very useful when use tool based automation. To me they're a huge headache to read. To me, the current dev guide style of documentation has been far more helpful in developing automation.

Daryl

On Oct 25, 2011, at 3:24 PM, Anne Gentle wrote:

Hi all -

Would also love Swagger. Nati looked into it and he thought it would require a Python client generator, based on reading that "Client generators are currently available for Scala, Java, Javascript, Ruby, PHP, and Actionscript 3." So in the meantime the QA list and Nati suggested WADL as a starting point for auto-generating simple API documentation while also looking towards Swagger for a way to document a public cloud like the Free Cloud. At the last OpenStack hackathon in the Bay Area (California), Nati worked through a simple WADL reader, he may be able to describe it better.

Hope that helps - sorry it's not more detailed than that but wanted to give some background, sounds like we all want similar outcomes and the resources for tasks to get us to outcomes is all we're lacking. QA Team, let me know how the Docs Team can work with you here.

Anne
Anne Gentle
anne@xxxxxxxxxxxxx<mailto:anne@xxxxxxxxxxxxx>
my blog<http://justwriteclick.com/> | my book<http://xmlpress.net/publications/conversation-community/> | LinkedIn<http://www.linkedin.com/in/annegentle> | Delicious<http://del.icio.us/annegentle> | Twitter<http://twitter.com/annegentle>
On Tue, Oct 25, 2011 at 2:41 PM, Joseph Heck <heckj@xxxxxxx<mailto:heckj@xxxxxxx>> wrote:
I expect this is going to open a nasty can of worms... today we don't have a consistent way of describing the APIs for the various services. I saw Nati's bug (https://launchpad.net/bugs/881621), which implies that all the services should have a WADL somewhere describing the API.

I'm not a huge fan of WADL, but the only other thing I've found is swagger (http://swagger.wordnik.com/spec).  I have been working towards trying to create an comprehensive OpenStack API documentation set that can be published as HTML, not unlike some of these:

       https://dev.twitter.com/docs/api
       http://developer.netflix.com/docs/REST_API_Reference
       http://code.google.com/p/bitly-api/wiki/ApiDocumentation#REST_API
       http://upcoming.yahoo.com/services/api/

To make this sort of web-page documentation effective, I think it's best to drive it from descriptions on each of the projects (if we can). I've checked with some friends who've done similar, and learned that most of the those API doc sets are maintained by hand - not generated from description files.

What do you all think about standardizing on WADL (or swagger) as a description of the API and generating comprehensive web-site-based API documentation from those description files? Does anyone have any other description formats that would work for this as an alternative?

(I admit I don't want to get into XML parsing hell, which is what it appears that WADL might lead too)

-joe


_______________________________________________
Mailing list: https://launchpad.net/~openstack<https://launchpad.net/%7Eopenstack>
Post to     : openstack@xxxxxxxxxxxxxxxxxxx<mailto:openstack@xxxxxxxxxxxxxxxxxxx>
Unsubscribe : https://launchpad.net/~openstack<https://launchpad.net/%7Eopenstack>
More help   : https://help.launchpad.net/ListHelp

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to     : openstack@xxxxxxxxxxxxxxxxxxx<mailto:openstack@xxxxxxxxxxxxxxxxxxx>
Unsubscribe : https://launchpad.net/~openstack
More help   : https://help.launchpad.net/ListHelp

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to     : openstack@xxxxxxxxxxxxxxxxxxx<mailto:openstack@xxxxxxxxxxxxxxxxxxx>
Unsubscribe : https://launchpad.net/~openstack
More help   : https://help.launchpad.net/ListHelp

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to     : openstack@xxxxxxxxxxxxxxxxxxx<mailto:openstack@xxxxxxxxxxxxxxxxxxx>
Unsubscribe : https://launchpad.net/~openstack
More help   : https://help.launchpad.net/ListHelp