<div dir="ltr">Hi All,<div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>Conversion</div><div>=========</div><div>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.</div><div><div><br class="">Backend</div><div>=======</div><div>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].</div></div><div><br></div><div>Front-end</div><div>========</div><div>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.</div><div><br></div><div><br></div><div>Other status</div><div>==========</div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div><br></div><div>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.</div><div><br></div><div><br></div><div><br></div><div>0. <a href="http://fairy-slipper.russellsim.org/">http://fairy-slipper.russellsim.org/</a></div><div>1. <a href="https://github.com/russell/fairy-slipper-migration/blob/master/api_doc/">https://github.com/russell/fairy-slipper-migration/blob/master/api_doc/</a></div><div>2. <a href="https://github.com/russell/fairy-slipper-migration/compare/tempest-log">https://github.com/russell/fairy-slipper-migration/compare/tempest-log</a><br clear="all"><div>3. <a href="https://github.com/russell/fairy-slipper-migration/blob/902fa40953eb3bdedd765a6a3770a6b75b4cf19f/api_doc/compute/v2.1/examples/startshost_resp_403.txt">https://github.com/russell/fairy-slipper-migration/blob/902fa40953eb3bdedd765a6a3770a6b75b4cf19f/api_doc/compute/v2.1/examples/startshost_resp_403.txt</a><br></div><div>4. <a href="https://github.com/russell/fairy-slipper-migration/blob/902fa40953eb3bdedd765a6a3770a6b75b4cf19f/api_doc/identity-admin/v2/examples/admin-listRolesForUserOnTenant_resp_403.txt">https://github.com/russell/fairy-slipper-migration/blob/902fa40953eb3bdedd765a6a3770a6b75b4cf19f/api_doc/identity-admin/v2/examples/admin-listRolesForUserOnTenant_resp_403.txt</a></div><div>5. <a href="https://github.com/russell/fairy-slipper-migration/blob/902fa40953eb3bdedd765a6a3770a6b75b4cf19f/api_doc/image/v2/examples/deleteImageTag-v2_resp_404.txt">https://github.com/russell/fairy-slipper-migration/blob/902fa40953eb3bdedd765a6a3770a6b75b4cf19f/api_doc/image/v2/examples/deleteImageTag-v2_resp_404.txt</a></div><div>6. <a href="https://coveralls.io/github/russell/fairy-slipper">https://coveralls.io/github/russell/fairy-slipper</a></div><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr">Cheers,<br>Russell Sim</div></div>
</div></div>