Open Stack

On 19/05/2016 14:09, Anne Gentle wrote:
>
>
> On Wed, May 18, 2016 at 1:42 PM, Hayes, Graham <graham.hayes at hpe.com
> <mailto:graham.hayes at hpe.com>> wrote:
>
>     I was moving Designate to the os-api-ref extension, and I spotted
>     something I thought we could do to improve the readability.
>
>
> Thank you!
>
>
>
>     Currently we have the HTTP Response Codes as a single
>     line on the page - I thought a table might be handy as well.
>
>     So, I had a go at it - and put up a POC[0]
>
>     It outputs a table with the code and the project reason for the code[1]
>
>     Example syntax is (used to generate [1]):
>
>          Response Codes
>          --------------
>
>          Normal
>          ^^^^^^
>
>          .. rest_response::
>
>             - 200: OK
>             - 100: Foo
>             - 201: Zone Created
>
>
>
>          Error
>          ^^^^^
>
>          .. rest_response::
>
>             - 405: Method *must* be POST
>             - 403: Policy does not allow current user to create zone
>             - 401: User must authenticate
>             - 400: Supplied data is malformed.
>             - 500: Something went wrong
>
>     Is this something worth pursuing? Should it be laid out differently?
>
>
> Definitely worth pursuing.
>
> How will teams get to more definitively describe the responses? For
> example, these descriptions for Compute errors:
>
> The operation is not allowed because the corresponding
> server is in a build state.
>
> or
>
> The operation is not allowed because the corresponding
> server is being re-sized or backed up.

Sure - they would do something like this:

   .. rest_response::

       - 409: The operation is not allowed because the corresponding 
server is in a build state.

Sean suggested having generic messages, and then allowing them to be 
overridden if the situation calls for it, which I am also looking at.

> If those descriptions are embedded in the Sphinx extension, I think
> we'll need to enable more detailed descriptions, and simply want to
> understand how. When I looked at the code, that was my question in the
> review - help me understand the mechanism better.

Yeah, definitely. Currently the only info embedded in the extension is
the RFC title ( so 200 has the the string "OK", 201 has "Created"
embedded).

I think it should really be a per project thing, with maybe an example
starter YAML file in the docs for os-api-ref?

-- Graham

> Thanks a bunch for doing this!
> Anne
>
>
>
>
>     Thanks,
>
>     -- Graham
>
>     0 - https://review.openstack.org/#/c/318281/1
>     1 - http://i.imgur.com/onsRFtI.png
>
>     _______________________________________________
>     OpenStack-docs mailing list
>     OpenStack-docs at lists.openstack.org
>     <mailto:OpenStack-docs at lists.openstack.org>
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
>
>
> --
> Anne Gentle
> www.justwriteclick.com <http://www.justwriteclick.com>