Open Stack

----- Original Message -----
> 
> 
> 
> On Sat, Nov 2, 2013 at 4:55 PM, Christopher Armstrong <
> chris.armstrong at rackspace.com > wrote:
> 
> 
> 
> On Sat, Nov 2, 2013 at 4:39 PM, Jay Pipes < jaypipes at gmail.com > wrote:
> 
> 
> Hi all,
> 
> One of the most important aspects in the early stages of Solum development
> will be the consensus building and stabilization of the Solum API
> specification. A solid API spec aid in the speeding up the pace of
> innovation in the Solum contributor community.
> 
> One of the aspects of the Keystone development process that I think is a big
> benefit is the separate source repository that stores the OpenStack Identity
> API specifications:
> 
> https://github.com/openstack/ identity-api
> 
> When new versions of the API specification are debated or new extensions are
> proposed, patches are made to the specification markdown documents and
> reviewed in the exact same manner that regular code is on the
> https://review.openstack.org Gerrit site. Contributors are free to annotate
> the proposed changes to the API specification in the same way that they
> would make inline code comments on a regular code review. Here's an example
> for a proposed change that I recently made:
> 
> https://review.openstack.org/# /c/54215/10
> 
> I'd like to propose that Solum do the same: have a separate source repository
> for the API specification.
> 
> Thoughts?
> -jay
> 
> 
> I like this idea. I'd also propose that the format of the specification be
> something machine-readable, such as API-Blueprint (a simple subset of
> markdown, apiblueprint.org , also what apiary uses, if you've ever seen
> that) or RAML (a more structured YAML-based syntax, raml.org ).
> API-Blueprint is closer to what the keystone document uses.
> 
> Making the documentation machine-readable means that it's much easier to
> verify that, in practice, the implementation of an API matches its
> specification and documentation, which is a problem that plagues many
> OpenStack projects right now.
> 
> 
> Hi all,
> I wouldn't expect you to know this unless you read minds, but we had a Summit
> session last week and a long email thread with all the PTLs prior to the
> Summit, and we decided to move all API specs into the repositories of the
> project itself, and stop maintaining separate "spec" repos.
> 
> The Etherpad is here:
> 
> https://wiki.openstack.org/wiki/Summit/Icehouse/Etherpads
> 
> We are working on a document to describe how to document your API both for
> future end-users and for current devs wanting to write to the specified
> needs of the API. Stay tuned to all the bat channels for that.
> 
> Happy to discuss further, but after 2 years, it's time to make some changes,
> and we worked hard to build consensus for the 10+ APIs we have in OpenStack.
> 
> Thanks,
> Anne
> 

While waiting for that to manifest, pandoc can do a reasonably good mediawiki -> markdown conversion.  Here's an example of the current API doc transliterated: https://gist.github.com/smarterclayton/7458182.

We can either check in a md format (for easy GitHub viewing) version into solum/ and iterate on that via code review, or hold off and iterate on the wiki page as it stands today.