On Thu, Mar 31, 2016 at 08:43:29AM -0400, Sean Dague wrote: > 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.
I assume at some point we'll be pulling the sphinx extension out to a separate project so that other projects can use this too? :) // jim > > -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 > > __________________________________________________________________________ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: [email protected]?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
