[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