<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Thu, May 7, 2015 at 11:04 AM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</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"><div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote"><div><div class="h5">On Thu, May 7, 2015 at 9:12 AM, Ildikó Váncsa <span dir="ltr"><<a href="mailto:ildiko.vancsa@ericsson.com" target="_blank">ildiko.vancsa@ericsson.com</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">
<div lang="SV" link="blue" vlink="purple">
<div>
<p class="MsoNormal"><span lang="EN-US">Hi All,<u></u><u></u></span></p>
<p class="MsoNormal"><span lang="EN-US"><u></u> <u></u></span></p>
<p class="MsoNormal"><span lang="EN-US">I missed the original thread with the registration to this list, so I will try to summarize my thoughts without history.<u></u><u></u></span></p>
<p class="MsoNormal"><span lang="EN-US"><u></u> <u></u></span></p>
<p class="MsoNormal"><span lang="EN-US">First of all, I support the idea of generating the API Reference from the source code as that is the most up to date source of information. On the other hand it makes much easier not just to create the exact document,
but keep it up to date, which is unfortunately not true for some of the projects that have their API guide in OpenStack Manuals.<u></u><u></u></span></p>
<p class="MsoNormal"><span lang="EN-US"><u></u> <u></u></span></p>
<p class="MsoNormal"><span lang="EN-US">As for the format and placement, I think it can be an experimental process as it is described in the corresponding blueprint. As there are still projects, which have their API documentation in the project tree it shows
that it is a viable solution too to put more responsibility on the project teams as opposed to leaving all on the documentation team, which has limited resources compared to the size of OpenStack at the moment.<u></u><u></u></span></p>
<p class="MsoNormal"><span lang="EN-US"><u></u> <u></u></span></p>
<p class="MsoNormal"><span lang="EN-US">As I mentioned the documentation, which lives together with the code, it raised a question for me. The API versioning is not always in line with the OpenStack releases neither with the changes on the API. As not every
project uses micro versioning or any kind of markup, which shows the changes, it can mean that the v2 version of an API contains less endpoints in let’s Juno, than in Kilo. If we document and update the API Reference based only on API versions, then we miss
to capture the difference between the functionality covered in the different OpenStack releases. In case of those projects, which maintains their documentation together with the code base this should not be an issue, as the documentation is frozen on the stable
branches, when those are cut from master. What do you think about this aspect? Is there a plan to address this issue too?</span></p></div></div></blockquote><div><br></div></div></div><div>Great point Ildiko. I need to be clear in the spec that the intent is to have a "Kilo" Dev Guide, a "Juno" Dev Guide, probably just maintaining 2 releases at a time (rather than the 3 that are security-supported). I think it'll have to lag a release behind, so that Dev Guides are only available for already-released services. </div></div></div></div></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"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><br></div><div>To keep the scope sane, I likely will start with Images v2.x API only. I'm reaching out to that team to see if that's feasible.</div><div><br></div><div>So it's not about the projects microversioning each resource call necessarily but about documenting "what can I do with a Juno-based cloud as an app dev" -- and document ways to self-discover that also. In your case, how would I know what calls are available in Juno, use stable branches? I guess I point the autodoc tool at the stable branch. Hm, this might mean some backported strings.</div></div></div></div></blockquote><div><br></div><div><div>So I woke up this morning and realized, there's no way we should be using stable/release branches to generate docs. The reviewers are fewer for those branches and less likely to know anything about API changes and uses. </div><div><br></div><div>That makes me realize we need to stay with the master branch for auto-generation. It also means that each call _will_ need to indicate which release it's intended for.</div><div><br></div><div>I'm still going to different meetings, such as the Nova API meeting, and reaching out to PTLs and API liaisons to continue to shape the spec. </div><div><br></div><div>Another area I need to add to the spec is using gabbi to test requests and responses. I'll also be writing up guidelines for docs within the API working group for reviewers to have as a rubric.</div><div><br></div><div>Keep asking questions, it's helping with the design effort.</div><div>Anne <br></div></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"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><br></div><div>Each resource should have some indicator in the docs whether it's available on Juno or Kilo, also. That's what's tougher for some APIs than others, right? </div><div><br></div><div>I really want to get the proof-of-concept robust enough to matter, so thanks for bringing up the versioning implications.</div><div><br></div><div>Anne</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"><div lang="SV" link="blue" vlink="purple"><div><p class="MsoNormal"><span lang="EN-US"><u></u><u></u></span></p>
<p class="MsoNormal"><span lang="EN-US"><u></u> <u></u></span></p>
<p class="MsoNormal"><span lang="EN-US">Best Regards,<u></u><u></u></span></p>
<p class="MsoNormal"><span lang="EN-US">Ildiko<u></u><u></u></span></p>
</div>
</div>
<br>_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">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>
<br></blockquote></div><span class=""><font color="#888888"><br><br clear="all"><div><br></div>-- <br><div>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</font></span></div></div>
</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>