Some more details on progress, because this is getting closer every day. There is now an api-ref target on the Nova project. The entire work in progress stream has been rebased into 2 patches to a top level api-ref/ directory structure in the Nova tree - https://review.openstack.org/#/q/status:open+project:openstack/nova+branch:master+topic:wip_api_docs2
That is a 2 patch series. The first is the infrastructure, the second is the content for 2 resources (versions and servers). The rendered output for this is at - http://docs-draft.openstack.org/63/298763/4/check/gate-nova-api-ref/6983838//api-ref/build/html/ (you can also pull and build locally with tox -e api-ref) Karen, Auggy, and Anne continue to work on the wadl data translator using the wadl2rst project and fairy-slipper to get various pieces of the structured data over. Hopefully we'll see some of those translated stacks rendering soon in patch sets. -Sean On 03/29/2016 07:56 AM, Sean Dague wrote: > Some additional links to what this sort of looks like right now - > http://docs-draft.openstack.org/71/298671/1/check/gate-nova-docs/c9e7f66//doc/build/html/rest_api/ > > Which is built off an RST file that looks like - http://tinyurl.com/hjqpjdm > > The notable additions are the ".. rest_method::" stanza, which is what > provides the collapsing method sections (as are in the current api-ref > site). > > As well as the ".. rest_parameters::" stanza which takes a list of > parameter names, and lookup keys to an external yaml file. This allows > for building the tables for these parameters much in the same way as the > existing WADL does but in a way where long for description can be easily > done. (Tables + rst are a bit cumbersome in the base case). > > The #1 Goal here is better docs for Humans. In all cases today, Humans > are the primary consumers of our API, building software that uses. A > large number of the current API docs have inaccuracies or are generally > confusing because few people have been able to ventured into the WADL to > make more than small typographic changes. > > Getting over to an RST base, that is content first in approach, will > hopefully open up the effort to more contributors. > > Swagger is neat. But it's important to remember it's actually an API > Design Tool, which provides the benefit of some documentation tooling > around it. If used in the Design phase of an API it imposes a set of > constraints that help build a solid API. Retrofiting to swagger is at > best difficult, and some of the features our APIs use make it impossible. > > This POC has mostly been about demonstrating what a content first > approach could be, where we could plug in structured / semi-structured > data via sphinx extensions. In phase 1, that will be our custom quick > and dirty markup format that's swagger inspired. In the future projects > could replace some of these plug points with other structured content in > their projects, like jsonschema / swagger / raml, whatever is appropriate. > > However, we need to make sure we don't delay moving forward to get off a > WADL base until we've perfected any of those other approaches. We're > living on brownfield that is on fire. Getting to higher ground is > priority one. Iterating after we're there will continue to happen. > > There is a cross project design summit session proposed for this work as > well, so we can show current status and discuss futures on this. > > As always, comments and questions welcomed. Our giant etherpad of doom > in poking at this work, and what's been discovered is here - > https://etherpad.openstack.org/p/api-site-in-rst > > -Sean > > On 03/28/2016 06:21 PM, Anne Gentle wrote: >> Hi all, >> >> This release I’ve been communicating about moving from WADL to Swagger >> for the API reference information on developer.openstack.org >> <http://developer.openstack.org>. What we've discovered on the journey >> is that Swagger doesn't match well for our current API designs (details >> below), and while we're not completely giving up on Swagger, we're also >> recognizing the engineering effort to maintain and sustain those efforts >> isn't going to magically appear. >> >> Sean Dague has put together a proof-of-concept with Compute servers >> reference documentation to use Sphinx, RST, parameters files, and some >> Sphinx extensions to do a near-copy representation of the API reference >> page. We've met with the Nova API team, the API working group, and other >> interested developers to make sure our ideas are sound, and so far we >> have consensus on forging a new path forward. The review patch is here: >> https://review.openstack.org/#/c/292420. >> >> I believe we can still find uses for the Swagger migration for some >> projects that match the specification really well. We'll keep outputting >> the draft Swagger files to http://developer.openstack.org/draft/swagger/ >> and continue to look for the use case for Swagger. Perhaps it's a >> try-it-out connection to TryStack. Maybe some projects will want to >> build clients from those files. We know it's useful, but need to focus >> efforts for now. >> >> We know that some OpenStack APIs cannot fit Swagger’s model. For >> example, Compute, File Storage, Bare Metal, and Block Storage (nova, >> manila, ironic, and cinder projects) have microversions enabled for >> updates to the request body as we continue to evolve the API definition, >> and Swagger has no mechanism to display the changes between >> microversions for end-users. As another example, Compute, Block Storage, >> File Storage, Databases, and Networks APIs (nova, cinder, manila, trove, >> and neutron projects) have an /actions resource that allows multiple >> differing request bodies. >> >> I'm writing this email to let you all know there's a new plan coming. We >> are using pieces of work from the past efforts to get the best outcome >> for sustainable, useful API documentation. The API Reference and WADL >> files will remain in the api-site repo until we have a new publishing >> job that we can use to flip the switch. >> >> We'll be writing a new specification as well as presenting at an >> upstream contributor's talk about Swagger as a standard: >> https://www.openstack.org/summit/austin-2016/summit-schedule/events/7723 >> Once we get the publishing pipeline established, look for review >> proposals to your project repos to store API docs there rather than in >> api-site. >> >> We're going to reboot the migration and get off of WADL. Three cheers >> for that. If you’d like to work on these efforts, please stay tuned to >> the usual mailing list channels and if you are a docs or API working >> group liaison, please stay up-to-date with the plans. Review the >> upcoming specification, look for API docs patches in your repo, review >> those, and keep the efforts moving. >> >> I'll also attend this week's cross-project meeting to be available for >> any questions during open discussion. >> >> Thanks, >> Anne, who is going to find her copy of the Oh Brother, Where Art Thou >> soundtrack now >> >> -- >> Anne Gentle >> Rackspace >> Principal Engineer >> www.justwriteclick.com <http://www.justwriteclick.com> >> >> >> __________________________________________________________________________ >> OpenStack Development Mailing List (not for usage questions) >> Unsubscribe: [email protected]?subject:unsubscribe >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> > > -- Sean Dague http://dague.net
signature.asc
Description: OpenPGP digital signature
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
