Open Stack

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: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
> 
> 


-- 
Sean Dague
http://dague.net

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160331/2354fae5/attachment.pgp>