[Openstack] Extension Documentation

Jorge Williams jorge.williams at rackspace.com
Fri Dec 16 22:12:04 UTC 2011


-----Original Message-----
From: Anne Gentle <anne at openstack.org>
Date: Fri, 9 Dec 2011 08:17:15 -0600
To: Jorge Williams <jorge.williams at rackspace.com>
Cc: "openstack at lists.launchpad.net (openstack at lists.launchpad.net)"
<openstack at lists.launchpad.net>
Subject: Re: [Openstack] Extension Documentation

>Hi everyone -
>Overall I support this effort and have discussed it at length with the
>Rackers working on it.
>I'd really like to get feedback from everyone who thinks they'll
>consume this type of information. I don't find it easy to use from an
>API consumer's perspective, but it is an absolute must for the
>projects to have a way to describe what parts of their API is an
>Here are my suggestions on this first iteration, which I've talked to
>Jorge about but also want to share with the list to get input.
>1. The header - at first it may confuse people since it's an OpenStack
>header on a Rackspace domain name. I understand this convention was
>chosen since you intend to give it over to OpenStack.

Right.  That's the intent.

>2. In the header, I don't believe "Extensions Documentation" is the
>correct label, probably just highlight "Documentation".

Okay, done.

>3. I don't have a good sense of how readers will get to API
>documentation from this page. With the API site also being worked on,
>we'll need to find a good secondary nav for these types of sites.

Can we start off by putting a link on "Related Resources" section on the
http://docs.openstack.org/api/ site?

>4. All of the links need to add an additional /content/ to the link to
>avoid redirects.

Okay, done.

>5. All of these "mini-docs" need to use a processing instruction or
>pom directive to avoid the tiny chunking and only chunk at the chapter

Okay, done for the compute extension,  I'll get working on the Keystone

>6. I made some minor changes to the DocBook template so that people
>can find the WADL normalizer tool.


>7. For the API site we're constructing, we're not yet sure how to
>handle extensions for the API reference. Right now we need to fill in
>a lot of reference information. Suggestions for integration are

If you're building a reference site, I suppose it makes sense to include
extension info as well as long as there's clear indication that it's an

>8. We need a discussion about who will review these extension
>submissions and ensure they get built.

So, for OpenStack extensions, then the PTL of the project should approve
and really as Waldon said the nova-api team in compute for example.
Vendor extensions should be reviewed by individual vendors.

>Based on the struggle to get these docs written, I also want to know
>if you all find the templates useful and think you'll author these.
>Any suggestions for the authoring side?

For sure, I'd love to have feedback on the templates myself :-)


>Brian, can we discuss at the nova-api meeting tomorrow at 3:00 CST in
>#openstack-manuals as well? I'll also discuss at the Doc Team meeting
>Monday 12/12 at 2:00 CST (20:00 UTC).
>Thanks for all the work here. Let's iterate on this site.
>On Thu, Dec 8, 2011 at 10:58 AM, Jorge Williams
><jorge.williams at rackspace.com> wrote:
>> Hi All,
>> I've started putting together a site to hold extension documentation.
>>You can see it here:
>> http://docs.rackspace.com/openstack-extensions/
>> The idea is to have a repository for all extensions, whether the
>>extension is an OpenStack extension or a vendor specific extension. It
>>makes sense to me that users can go to a central place to get extension
>>docs regardless of where the extension came from or who wrote it, etc.
>>I'm putting this out as somewhat of a proposal with the hopes that we
>>can roll this page into our own docs site. The site is *somewhat*
>>automated. If you put the webhelp output that comes out of our docs tool
>>chain, it will reach into the extension description sample for info
>>about the extension and just roll it into the index page.  The idea is
>>that we can have something like Jenkins spit out some webhelp to a
>>directory and things will just work. The script that does this is
>>written in perl though If anyone wants to take a stab at rewriting it in
>>another language I'm all for it.  You can find it here:
>> https://github.com/RackerWilliams/extension-docs
>> What I'm really interested in right now is in getting good accurate
>>docs for our extensions and putting them out there it a central place
>>where people can see.  If you have info about a particular extension
>>send it over.  There are pointers to doc templates at the bottom of the
>>page and I know that I'll be working on documenting some of the
>>extension that are currently out there for compute. BTW:  Take the
>>compete  extensions that are out there at this very moment with a grain
>>of salt  as some of these are still under development.
>> Finally, I've updated the extension guide based on feedback from folks.
>> You can find the guide here:
>> Note that the document is still a draft, so things are likely to change
>>-- though I don't reckon dramatically. We're planning on having a wider
>>discussion about extensions in the next nova-api team meeting on friday.
>> Questions?  Thoughts?
>> -jOrGe W.
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to     : openstack at lists.launchpad.net
>> Unsubscribe : https://launchpad.net/~openstack
>> More help   : https://help.launchpad.net/ListHelp

More information about the Openstack mailing list