Open Stack

On 04/14/2016 05:03 AM, Markus Zoeller wrote:
>> 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.

Yes, that is the intent. Auggy is working up a tool that will let us
bulk create this fleet of bugs with detailed instructions so they will
be easy to work through by new folks. This may also be extremely useful
for other low hanging fruit tracking mass efforts in the future.

	-Sean

-- 
Sean Dague
http://dague.net