Open Stack

On 11/07/2012 05:09 PM, Anne Gentle wrote:
<snip>
>
> So, api.openstack.org was originally an experiment to get all the
> extensions in one place, but I do believe it has met that objective
> and now it's time to stop confusing people with "what's the difference
> between docs.openstack.org/api and api.openstack.org? So that's the
> first step - get a more descriptive landing page on api.openstack.org
> rather than a long list of calls.

Honestly, having spent a bunch of time with api.openstack.org and the 
os-compute-api manual recently, I'm not sure we're doing ourselves any 
favors but having api.openstack.org as a seperate thing.

The os-compute-api manual is really good (I'll assume the same of the 
others), really complete, and having something else that people tend to 
get stuck on first which isn't anywhere nearly as good, seems counter 
productive.

>> api.openstack.org/python => Would be a place for examples of using the
>> Python bindings API exposed by python-*client packages. Would NOT be a
>> place for examples of using the CLI tools, though... that documentation
>> would/should live in the administrator's guide IMHO
>
> We do have a new-ish CLI guide [1] for all the OpenStack CLIs linked
> from the docs landing page. So I agree here and the content is shared
> with the Compute Admin Manual too.

>> So, for instance, api.openstack.org/python/compute would show examples
>> like this:
>>
>> from novaclient.v1_1 import client
>> c = client.Client(USER, PASS, TENANT, AUTH_URL, service_type="compute")
>>
>> for s in c.servers.find(host="myhost"):
>>      print s.id, s.name
>>
>> But not examples like this:
>>
>> $> nova list --host=myhost
>
> I always like for URLs to self-describe what's going on. Not sure if
> we have to get this fine a point on it but I'll certainly take it into
> consideration for the api site work. The work so far is:
>
> -Track bugs against api.openstack.org at a new Launchpad project,
> openstack-api-site.
> -Change CI Infrastructure builds to build from a new
> openstack/api-site repo on GitHub.
>
> What'll happen next is to change the landing page at api.openstack.org
> so the long listing is a sub-page, api.openstack.org/api-ref.html.
> Then I'll also redirect from docs.openstack.org/api to
> api.openstack.org. I think the landing page is going to be:
>
> API Reference
> API Specs
> SDKs
>
> Then when you click through to API Reference we can start to build out
> all these examples and finish out the blueprint to bring in all the
> tested Compute API samples.
>
> I don't know if we have to do /python/ /http/ /php/ /java/ sub
> directories but that might be fine, what do others think of Jay's
> examples?

Having a place for examples is a great idea. That should really support 
user generated content though, I think git ends up being too high a 
barrier on that one, because the folks that you want those examples from 
are often not going to be developers.

I've worked with sgml on and off for a decade, and it still makes me 
confused. :) I can imagine that it's really hard for end users where 
great examples could come from.

> I'd also like to get much more practical documentation than spec
> documentation. Where do all these code samples come from? The amount
> of work to integrate hundreds of new Compute code samples is a long
> list, we'll just piece through it, but do other APIs have that many
> tested examples (hundreds)? Let me know how to find 'em and I'll find
> a way to integrate them and be smart about it. I haven't found many
> people willing to do the tedious API doc work so if you're even
> thinking of helping out, please do so!
>
> Thanks for keeping on it you all!
> Anne
>
>> We could further have examples for any other language bindings follow
>> the same kind of sitemap structure.
>>
>> Thoughts?
>> -jay
>
> [1] http://docs.openstack.org/cli/quick-start/content/index.html
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>


-- 
Sean Dague
IBM Linux Technology Center
email: sdague at linux.vnet.ibm.com
alt-email: sldague at us.ibm.com