<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Aug 5, 2013 at 8:55 AM, John Garbutt <span dir="ltr"><<a href="mailto:john@johngarbutt.com" target="_blank">john@johngarbutt.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Given we seem to be leaning towards WSME:<br>
<a href="http://lists.openstack.org/pipermail/openstack-dev/2013-August/012954.html" target="_blank">http://lists.openstack.org/pipermail/openstack-dev/2013-August/012954.html</a><br>
<br>
Could we not try to make WSME give us the documentation we need?<br>
<br>
Not sure if its feasible, but it seems like there is a good start to<br>
that already available:<br>
<a href="https://wsme.readthedocs.org/en/latest/document.html" target="_blank">https://wsme.readthedocs.org/en/latest/document.html</a><br>
<br></blockquote><div><br></div><div>John, this looks interesting, but I have reservations. Do you know if you can suppress the SOAP and ExtDirect entries? </div><div><br></div><div>Also we already have available the current way to create API docs for <a href="http://api.openstack.org/api-ref.html">http://api.openstack.org/api-ref.html</a>. </div>
<div><br></div><div>I'm not excited about an inconsistent user experience for reading REST API docs for one project but not others. Where will it be published? How will readers find it? And so on. It's good for Compute to lead the way and try things, but I'd like to know if other projects are willing to follow? Looking for input from other projects.</div>
<div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
John<br>
<div><div class="h5"><br>
On 5 August 2013 08:44, Christopher Yeoh <<a href="mailto:cbkyeoh@gmail.com">cbkyeoh@gmail.com</a>> wrote:<br>
> Hi,<br>
><br>
> I'd like to extend the information we produce with the Nova v3 API samples<br>
> in order to make it easier to automate as much as possible the generation of<br>
> a specification document. This should make it easier to keep the<br>
> documentation more accurate and up to date in the future. I believe that if<br>
> we generate a meta file for each xml and json response file which includes<br>
> some information which describes the method for the api sample and ties<br>
> together the request and response files we can do this.<br>
><br>
> I've put together a bit of a prototype here (the patch is very ugly at the<br>
> moment, just proof of concept)<br>
><br>
> <a href="https://review.openstack.org/#/c/40169/" target="_blank">https://review.openstack.org/#/c/40169/</a><br>
><br>
> An example of the hosts extension method to put a host into or out of<br>
> maintenance mode, a file called host-put-maintenance-resp.json.meta is<br>
> created:<br>
> :<br>
><br>
> {<br>
> "description": "Enables a host or puts it in maintenance mode.",<br>
> "extension": "os-hosts",<br>
> "extension_description": "Manages physical hosts.",<br>
> "method": "PUT",<br>
> "request": "host-put-maintenance-req.json",<br>
> "response": "host-put-maintenance-resp.json",<br>
> "section_name": "Hosts",<br>
> "status": 200,<br>
> "url": "os-hosts/{host_name}"<br>
> }<br>
><br>
> A separate metafile is created for each api sample response rather than<br>
> trying to accumulate them by extension because this way it allows for the<br>
> tests to still be run in parallel. The metafile also adds the logging of the<br>
> status code expected which is not currently done and I think an important<br>
> part of the API.<br></div></div></blockquote><div><br></div><div>Wow what's your guess on how many files this will be? Trying to think of this from a doc management standpoint for troubleshooting when the output is incorrect.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div class="h5">
><br>
> On the documentation side we'd have a script collate all the metafiles and<br>
> produce the bulk of the specification document.<br></div></div></blockquote><div><br></div><div>I'd like to see the results of that script, and it's good you're thinking about docs. But if you create the docs from the code it's not quite a spec, what if the code is incorrect? Maybe I misunderstand.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div class="h5">
><br>
> The changes to the api sample test code is fairly minor:<br>
><br>
> class HostsSampleJsonTest(api_sample_base.ApiSampleTestBaseV3):<br>
> extension_name = "os-hosts"<br>
> section_name = "Hosts"<br>
> section_doc = "Manages physical hosts."<br>
><br>
> def test_host_startup(self):<br>
> response = self._do_get(<br>
> 'os-hosts/%s/startup', self.compute.host, 'host_name',<br>
> api_desc='Starts a host.')<br>
> subs = self._get_regexes()<br>
> self._verify_response('host-get-startup', subs, response, 200)<br>
><br>
> def test_host_maintenance(self):<br>
> response = self._do_put(<br>
> 'os-hosts/%s', self.compute.host, 'host_name',<br>
> 'host-put-maintenance-req', {},<br>
> api_desc='Enables a host or puts it in maintenance mode.')<br>
> subs = self._get_regexes()<br>
> self._verify_response('host-put-maintenance-resp', subs, response,<br>
> 200)<br>
><br>
><br>
> - some definitions per extension and a description for the method per test<br>
> so I don't think its a significant burden for developers or reviewers.<br>
><br>
> I'd like to know what people think about heading in this direction, and if<br>
> there is any other information we should include. I'm not currently<br>
> intending on including this in the first pass of porting the api samples<br>
> tests to v3 (I don't think there is time) nor to backport to V2.<br>
><br></div></div></blockquote><div><br></div><div>I fully support these efforts, and I just want to be sure I understand the eventual outcomes and ramifications.</div><div>Thanks,</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div><div class="h5">
> Regards,<br>
><br>
> Chris<br>
><br>
</div></div>> _______________________________________________<br>
> OpenStack-dev mailing list<br>
> <a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
><br>
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</div></div>