Open Stack

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