[openstack-dev] [nova] Nova API doc import, and next steps
Markus Zoeller
mzoeller at de.ibm.com
Thu Apr 14 09:03:15 UTC 2016
> From: Sean Dague <sean at dague.net>
> To: openstack-dev at lists.openstack.org
> Date: 04/13/2016 05:08 PM
> Subject: [openstack-dev] [nova] Nova API doc import, and next steps
>
> I think we've gotten the automatic converters for the wadl files to
> about as good as we're going to get. The results right now are here -
> https://review.openstack.org/#/c/302500/
>
> There remain many issues in the content (there are many issues in the
> source content, and a few crept in during imperfect translation),
> however at some point we need to just call the automatic translation
> effort "good enough", commit it, and start fixing the docs in chunks. I
> think we are at that stage.
>
> Once we get those bits committed, it's time to start fixing what
> remains. I started an etherpad for the rough guide here -
> https://etherpad.openstack.org/p/nova-api-docs-in-rst there are a few
> global level things, but a bunch of this is a set of verifications and
> fixes that will have to happen for every *.inc file.
>
> for every file in api-ref/sources/*.inc
>
> 1. Verify methods
> 1. Do all methods of the resource currently exist?
> 2. Rearange methods in order (sorted by url)
> 1. GET
> 2. POST
> 3. PUT
> 4. DELETE
> 5. i.e. for servers.inc GET /servers, POST /servers, GET
> /servers/details, GET /servers/{id}, PUT /servers/{id},
> DELETE /servers/{id}
> 2. Verify all parameters
> 1. Are all parameters that exist in the resource are listed
> 2. Are all parameters referencing the right lookup value in
> parameters.yaml
> 1. name, id are common issues, will need $foo_name and
$foo_id
> created
> 3. Add microversion parameters at the end of the table in order
of
> introduction
> 1. min_ver: 2.10 is a valid parameter key
> 3. Examples
> 1. Is there an example response for all request / response that
> have
> a body
> 2. Is there an english description of the change in question
> explaining the action that it would have
> 4. Body Text
> 1. Is formatting of the introduction text for each section well
> formatted (lists and headers were stripped in the
processing)
>
> My feeling is that we should probably create a fleet of bugs which is 1
> per source file and phase, with a set of api-ref tags. This will give us
> easy artifacts to hand off to people, and know which ones are getting
> done and which ones remain. A lot of this work is pretty easy, just
> takes some time.
>
> I'd like to get the base patches landed in the next day or so so that we
> can start chugging through these fixes pre summit, and do a virtual doc
> sprint post summit to push through to completion.
>
> -Sean
>
> --
> Sean Dague
> http://dague.net
The rendered output looks pretty neat. I like that all is on one page:
http://docs-draft.openstack.org/00/302500/9/check/gate-nova-api-ref/81d644c/api-ref/build/html/
One bug report per source-file sounds reasonable. Adding the
"low-hanging-fruit" tag will maybe get you some volunteers.
Regards, Markus Zoeller (markus_z)
More information about the OpenStack-dev
mailing list