Open Stack

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 <cbkyeoh at gmail.com> 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
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>