Open Stack

Hi All,

Just thought I should give an update on the current progress of the API
generation RST work we've been doing a.k.a Fairy-Slipper.

My original outlandish dreams, being able to develop the best documentation
site ever conceived, have been subtly reduced.  So I'm trying to reach
feature parity with the current API docs without doing anything too fancy
first.

Conversion
=========
We have things converting from WADL in a stable way with most markup being
supported and conversions covered by unit tests.  There are still some
bugs, but mostly it works.  Karen added tables and links, which were
probably the 2 biggest missing items.

Backend
=======
The front-end is currently relying on a Pecan based website to render the
RST files[1] into Swagger,  I have created a repository on github to to
give greater visibility of the resulting RST files and any intermediate
files.  The master branch of this is what is being displayed on the demo
website [0].

Front-end
========
The front-end is currently a blend of AnguarJS libraries,  and is entirely
fed off our modified swagger [0].  So the website could function as a
static site with no requirement for any running server.  It's still
requiring a bit of work to fix/display schemas and dynamically load some
resources.  But it's almost usable as a basic site.


Other status
==========
The integration into the Routes framework was recently tested, it's working
as a prototype, but I haven't focused on it, since it would require a
conversion to RST first.  So I figure that the effort is better spent
getting a working replacement for the existing API docs before any effort
to move the content to other projects.

We are currently sitting at about 64% coverage, which is OK, but not
flash.  Karen Bradshaw has been a great help extending the conversion to
cover new syntax and  extending the test coverage, even though the whole
RST -> Markdown conversion seems crazy.

I have also put a little work into parsing the Tempest gate job log files,
so that examples can be pulled from it instead of the current hand crafted
request response examples.  I have a separate branch that demonstrates this
functionality [2] probably the best thing that it offerers is some easy
access to error messages produced by the negative tests in Tempest
[3][4][5]. The idea of this process being that as tempests coverage expands
so does our ability to easily capture examples.   I could probably whip up
a similar tool for working with any of the CLI tools so that we get
consistent examples for all the different calls even untested ones.  At the
moment I pull about ~750 examples from a normal tempest run.


Any and all feedback is welcome.  I'm sorry progress hasn't been faster,
but I'm doing this in my own time and sometimes life gets in the way.



0. http://fairy-slipper.russellsim.org/
1. https://github.com/russell/fairy-slipper-migration/blob/master/api_doc/
2. https://github.com/russell/fairy-slipper-migration/compare/tempest-log
3.
https://github.com/russell/fairy-slipper-migration/blob/902fa40953eb3bdedd765a6a3770a6b75b4cf19f/api_doc/compute/v2.1/examples/startshost_resp_403.txt
4.
https://github.com/russell/fairy-slipper-migration/blob/902fa40953eb3bdedd765a6a3770a6b75b4cf19f/api_doc/identity-admin/v2/examples/admin-listRolesForUserOnTenant_resp_403.txt
5.
https://github.com/russell/fairy-slipper-migration/blob/902fa40953eb3bdedd765a6a3770a6b75b4cf19f/api_doc/image/v2/examples/deleteImageTag-v2_resp_404.txt
6. https://coveralls.io/github/russell/fairy-slipper

-- 
Cheers,
Russell Sim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150928/d379ff3b/attachment.html>