On Fri, May 19, 2017 at 8:00 AM, Sean Dague <s...@dague.net> wrote: > On 05/19/2017 08:36 AM, Monty Taylor wrote: > > On 05/17/2017 10:14 AM, Joe Topjian wrote: > >> > >> > >> On Tue, May 16, 2017 at 4:13 PM, Monty Taylor <mord...@inaugust.com > >> <mailto:mord...@inaugust.com>> wrote: > >> > >> Hey all! > >> > >> I read the API docs A LOT. (thank you to all of you who have worked > >> on writing them) > >> > >> As I do, a gotcha I hit up against a non-zero amount is mapping the > >> descriptions of the response parameters to the form of the response > >> itself. Most of the time there is a top level parameter under which > >> either an object or a list resides, but the description lists list > >> the top level and the sub-parameters as siblings. > >> > >> So I wrote a patch to os-api-ref taking a stab at providing a way to > >> show things a little differently: > >> > >> https://review.openstack.org/#/c/464255/ > >> <https://review.openstack.org/#/c/464255/> > >> > >> You can see the output here: > >> > >> > >> http://docs-draft.openstack.org/55/464255/5/check/gate- > nova-api-ref-src/f02b170//api-ref/build/html/ > >> > >> > >> <http://docs-draft.openstack.org/55/464255/5/check/gate- > nova-api-ref-src/f02b170//api-ref/build/html/> > >> > >> > >> If you go expand either the GET / or the GET /servers/details > >> sections and go to look at their Response sections, you can see it > >> in action. > >> > >> We'd like some feedback on impact from humans who read the API docs > >> decently regularly... > >> > >> The questions: > >> > >> - Does this help, hurt, no difference? > >> > >> > >> It helps. It seems noisy at first glance, but the information being > >> denoted is important. It's one of those situations where once you start > >> reading deeper into the information, this kind of markup makes the API > >> more understandable more quickly. > > > > Awesome. Thanks! > > > >> - servers[].name - servers is a list, containing objects with a name > >> field. Good or bad? > >> - servers[].addresses.$network-name - addresses is an object and > the > >> keys of the object are the name of the network in question. > >> > >> > >> Again, these seem noisy at first, but having parsed complex paths, > >> especially the above address info, by dumping variables too many times, > >> I really appreciate the above syntax. > >> > >> Going even further: > >> > >> servers[].addresses.$network-name[].OS-EXT-IPS-MAC:mac_addr > >> > >> looks a mess, but I can see how exactly to navigate to the leaf as well > >> as understand what types make up the path. Being able to succinctly > >> (relatively/subjectively speaking) describe something like the above is > >> very helpful. This definitely gets my support. > > > > Sweet. thanks for the feedback! I just pushed up a new rev yesterday > > based on some feedback from Anne: > > > > http://docs-draft.openstack.org/55/464255/5/check/gate- > nova-api-ref-src/f02b170//api-ref/build/html/ > > http://docs-draft.openstack.org/55/464255/7/check/gate- > nova-api-ref-src/88a33cc//api-ref/build/html/ > is actually the revision with the <strong> tags.
+1 on the <strong> tags.
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
