[openstack-dev] [horizon][api][docs] Feedback requested on proposed formatting change to API docs
Monty Taylor
mordred at inaugust.com
Fri May 19 12:36:47 UTC 2017
On 05/17/2017 10:14 AM, Joe Topjian wrote:
>
>
> On Tue, May 16, 2017 at 4:13 PM, Monty Taylor <mordred at inaugust.com
> <mailto:mordred at 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/
That adds <strong> tags around the leaf element. so basically:
servers[].addresses.$network-name[].OS-EXT-IPS-MAC:mac_addr
becomes
servers[].addresses.$network-name[].**OS-EXT-IPS-MAC:mac_addr**
which I hope will ease any confusion when leaf elements have punctuation
in their names - like OS-EXT-IPS-MAC:mac_addr
More information about the OpenStack-dev
mailing list