----- Original Message ----- > > > > On Sat, Nov 2, 2013 at 4:55 PM, Christopher Armstrong < > [email protected] > wrote: > > > > On Sat, Nov 2, 2013 at 4:39 PM, Jay Pipes < [email protected] > 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. _______________________________________________ OpenStack-dev mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
