> From: Sean Dague <[email protected]> > To: [email protected] > 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) __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
