<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Apr 28, 2015 at 9:01 PM, Tom Fifield <span dir="ltr"><<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Hi all,<br>
<br>
I'm writing to you because I think we should seriously consider<br>
generating the API reference at least partially from the code itself,<br>
rather than continuing to maintain a separate set of documents that has<br>
no relationship with the code.<br></blockquote><div><br></div><div>I definitely want to seriously consider autogenerating, but for the reference portion only. It's important to bring up the quality of the API docs by not purely autogenerating (I know you're not advocating for that) but for strategically scraping. I like the ideas you have; more below.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
No-one can argue that it's an enormous amount of work to maintain an API<br>
reference. Despite our best efforts, our API reference is incomplete and<br>
inaccurate - you need only check the bug list[1] to know this.<br>
<br>
The move to swagger[2] will help some of this, but it's not enough. Even<br>
with new tooling, we are still stuck in a world of manual updates and<br>
effort - spending a large amount of time converting a python<br>
method/class definition into another format.<br>
<br>
We do add great value in the descriptions of parameters, groupings and<br>
overall display of the information. Diane is simply amazing here. So,<br>
wouldn't it be great if we could focus just on that, without needing to<br>
worry about changing this python docstring:<br>
<br>
"""<br>
Move your app forward with the Uber API<br>
"""<br>
<br>
into this swagger description:<br>
<br>
info:<br>
  description: Move your app forward with the Uber API<br>
<br>
<br>
and instead fix up the string itself ?<br>
<br>
<br>
The move-to-swagger spec at the moment says: "We don't really want<br>
autogenerated API documentation, because then how do you know if the<br>
code is correct?". Which is really quite odd - because looking at the<br>
code is exactly what developers, SDK makers and users are doing right<br>
now when confronted with our incomplete, inaccurate documentation :) The<br>
code is what defines the API - it's what actually processes the requests<br>
and responses. If there's a problem where the implementation of that<br>
processing is incorrect - we fix that in the code, not by telling users<br>
something completely different in a document :)<br></blockquote><div><br></div><div>Well, we certainly won't solve the problem of inaccuracy by relying on inaccurate code! But what I think will help is the API Working Group's reviews and ensuring no backwards compatible changes get introduced. So the tactic here is to ask the API WG to tackle the "contractual agreement" portion of reviews that have APIImpact. Plus, keeping reviews with the core teams will help immensely in keeping up with change.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
We may yet get to the point where OpenStack APIs are<br>
designed-in-document first, then implemented, but we're far from that at<br>
the moment and have much more pressing problems to solve.<br></blockquote><div><br></div><div>Agreed, and we have years of data to back that up.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
There are a number of python integrations that swagger supports[3].<br>
Essentially, what these would allow us to do is use portions of the code<br>
to generate swagger specs. This means that our documentation would<br>
always be complete and accurate to what users actually experience when<br>
they interact with OpenStack APIs. </blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
The automation of option tables in the configuration reference is a good<br>
parallel here. We used to have very incomplete and often outdated<br>
configuration tables. After the automation, literally hundreds of bugs<br>
have been solved with very little human intervention. The problem just<br>
doesn't exist anymore, and we've clawed back some of our precious resources.<br>
<br>
In the config-ref there are two types of auto-magic: non-swift, where<br>
all text lives in the code and updates should be done there; and swift,<br>
where the option name comes from the code, but the descriptive text must<br>
be manually entered - overwriting a default label of "No help text<br>
available for this option".<br>
<br>
Applying that to API documents, I think it would be amazing to try the<br>
former: it basically means that developers write their own API<br>
documentation, happily, in the code, in a format they are familiar with.<br>
We can take that and generate swagger for the API-ref and display it<br>
appropriately.<br>
<br>
However, that might not be possible, or might be too much work for a<br>
single release. So, the second option is still a very good one - we use<br>
automation to extract some information (eg it could be just class<br>
titles, doc strings, parameter names) to generate swagger specs with the<br>
placeholder text that we-as-the-docs-team can fill in with our best<br>
efforts - which are excellent, since we're the pros at strings :)<br></blockquote><div><br></div><div>I think this is a great first step, and I'd like to scope it to infrastructure services only as well to keep the scope do-able.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
The important thing is that this should be done continuously[4], as with<br>
the config-ref, to ensure accuracy and completeness. Just looking at the<br>
first 75 bugs in api-site[5], this approach would solve almost all of<br>
them. This isn't something you can say about simply switching formats ;)<br></blockquote><div><br></div><div>True. I do not want to switch formats only. I want to paint a picture of the best future for this doc set. The overarching goals are:</div><div>- better process for keeping docs updated</div><div>- more trust in the accuracy of the API reference docs</div><div><br></div><div>I think by moving sourcing closer to the project repos themselves it'll help with both goals. We'll just have to place accuracy and consumer advocacy high in the review priority.</div><div><br></div><div>These new developer guides should enable app devs to make powerful apps on OpenStack clouds. Those developer guides will be reviewed by the API WG, the service devs themselves, and dev doc writers. Let's automate where it makes sense to. The approach is not purely auto-generation -- that only gets us halfway there. We also have to source docs where the best reviewers live. We can insert narrative, helpful content that is heavily reviewed, vetted, and offers high quality. The contract agreement burden can happen at review time (for this iteration, we can tackle gated validation next if we like).</div><div><br></div><div>Let's scrape code for resources, parameters, headers, requests and responses, that'll definitely help. In doing so we can bake-in the versioning of the API reference, does this run on icehouse? sorts of questions.</div><div><br></div><div>I'll update the docs-spec, and I think I can get some great wireframes in time for the Summit that show how awesome the future can be. I'll need web dev, Python development, and time, but this is definitely shaping into something do-able. Sweet.</div><div><br></div><div>I appreciate the API WG letting me discuss and shape with them at their meeting this week also; feel free to read that log if you want to catch up. [1]</div><div><br></div><div>Anne</div><div><br></div><div>1. <a href="http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-04-30-00.01.log.html">http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-04-30-00.01.log.html</a></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
Anyway, thank you if you've managed to get to this point. I think we<br>
have a great opportunity here to make a very significant change to the<br>
way we do API documentation, and free up our previous docs resources to<br>
really focus on the things we do best, rather than spending a lot of<br>
time changing one arcane syntax into another :)<br>
<br>
<br>
Regards,<br>
<br>
<br>
<br>
Tom<br>
<br>
[1] <a href="https://bugs.launchpad.net/openstack-api-site" target="_blank">https://bugs.launchpad.net/openstack-api-site</a><br>
[2] <a href="https://review.openstack.org/#/c/177934/" target="_blank">https://review.openstack.org/#/c/177934/</a><br>
[3] <a href="https://github.com/swagger-api/swagger-spec#python" target="_blank">https://github.com/swagger-api/swagger-spec#python</a> , I found there's<br>
a worked example showing the output of the swagger UI for<br>
django-rest-swagger at:<br>
<a href="http://django-rest-swagger.readthedocs.org/en/latest/examples.html" target="_blank">http://django-rest-swagger.readthedocs.org/en/latest/examples.html</a><br>
[4] Kinda once a milestone is how we're doing it with config-ref at the<br>
moment, but this could in theory be fully automated<br>
[5] <a href="https://bugs.launchpad.net/openstack-api-site/+bugs?orderby=id&start=0" target="_blank">https://bugs.launchpad.net/openstack-api-site/+bugs?orderby=id&start=0</a><br>
<br>
-------- Forwarded Message --------<br>
Subject: [Blueprint autogenerate-api-reference] Autogenerate API Reference<br>
Date: Mon, 27 Apr 2015 15:14:41 -0000<br>
From: Anne Gentle <<a href="mailto:anne@openstack.org">anne@openstack.org</a>><br>
Reply-To: Anne Gentle <<a href="mailto:anne@openstack.org">anne@openstack.org</a>><br>
To: <a href="mailto:tom@openstack.org">tom@openstack.org</a><br>
<br>
Blueprint changed by Anne Gentle:<br>
<br>
Whiteboard set to:<br>
We don't really want autogenerated API documentation, because then how<br>
do you know if the code is correct? How can a quality engineer or SDK<br>
dev trust the output? Autogeneration is fine for the first set of docs<br>
but after that need to be treated as the "contract" for SDK developers<br>
to trust.<br>
<span class=""><font color="#888888"><br>
--<br>
Autogenerate API Reference<br>
<a href="https://blueprints.launchpad.net/openstack-manuals/+spec/autogenerate-api-reference" target="_blank">https://blueprints.launchpad.net/openstack-manuals/+spec/autogenerate-api-reference</a><br>
<br>
<br>
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</font></span></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature">Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</div></div>