Given we seem to be leaning towards WSME: http://lists.openstack.org/pipermail/openstack-dev/2013-August/012954.html
Could we not try to make WSME give us the documentation we need? Not sure if its feasible, but it seems like there is a good start to that already available: https://wsme.readthedocs.org/en/latest/document.html John On 5 August 2013 08:44, Christopher Yeoh <[email protected]> wrote: > Hi, > > I'd like to extend the information we produce with the Nova v3 API samples > in order to make it easier to automate as much as possible the generation of > a specification document. This should make it easier to keep the > documentation more accurate and up to date in the future. I believe that if > we generate a meta file for each xml and json response file which includes > some information which describes the method for the api sample and ties > together the request and response files we can do this. > > I've put together a bit of a prototype here (the patch is very ugly at the > moment, just proof of concept) > > https://review.openstack.org/#/c/40169/ > > An example of the hosts extension method to put a host into or out of > maintenance mode, a file called host-put-maintenance-resp.json.meta is > created: > : > > { > "description": "Enables a host or puts it in maintenance mode.", > "extension": "os-hosts", > "extension_description": "Manages physical hosts.", > "method": "PUT", > "request": "host-put-maintenance-req.json", > "response": "host-put-maintenance-resp.json", > "section_name": "Hosts", > "status": 200, > "url": "os-hosts/{host_name}" > } > > A separate metafile is created for each api sample response rather than > trying to accumulate them by extension because this way it allows for the > tests to still be run in parallel. The metafile also adds the logging of the > status code expected which is not currently done and I think an important > part of the API. > > On the documentation side we'd have a script collate all the metafiles and > produce the bulk of the specification document. > > The changes to the api sample test code is fairly minor: > > class HostsSampleJsonTest(api_sample_base.ApiSampleTestBaseV3): > extension_name = "os-hosts" > section_name = "Hosts" > section_doc = "Manages physical hosts." > > def test_host_startup(self): > response = self._do_get( > 'os-hosts/%s/startup', self.compute.host, 'host_name', > api_desc='Starts a host.') > subs = self._get_regexes() > self._verify_response('host-get-startup', subs, response, 200) > > def test_host_maintenance(self): > response = self._do_put( > 'os-hosts/%s', self.compute.host, 'host_name', > 'host-put-maintenance-req', {}, > api_desc='Enables a host or puts it in maintenance mode.') > subs = self._get_regexes() > self._verify_response('host-put-maintenance-resp', subs, response, > 200) > > > - some definitions per extension and a description for the method per test > so I don't think its a significant burden for developers or reviewers. > > I'd like to know what people think about heading in this direction, and if > there is any other information we should include. I'm not currently > intending on including this in the first pass of porting the api samples > tests to v3 (I don't think there is time) nor to backport to V2. > > Regards, > > Chris > > _______________________________________________ > OpenStack-dev mailing list > [email protected] > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > _______________________________________________ OpenStack-dev mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
