<br><br><div class="gmail_quote">On Tue, Nov 13, 2012 at 5:36 PM, heckj <span dir="ltr"><<a href="mailto:heckj@mac.com" target="_blank">heckj@mac.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Hey Mark,<br>
<br>
I got a bug this weekend with wanting to clean up the docstrings and doing something to document those libraries that we're using. CFG is in great shape, some of others - well, not so much. Anyway, the pending review expands upon the basic sphinx work, adding the openstack sphinx templates and formatting, and cleaning up the warnings that existed.<br>

<br>
What's our thought for how to present these docs as this project fissions into separate libraries? Do we make and keep a separate sphinx-doc with each fissioned library? Publish those to <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a> like we do with keystone, glance, nova, etc.?<br>

<br>
Since these are mostly heading to PyPi as a primary target (my point of view, disabuse me of the notion if that's radically incorrect), do we want to consider setting up docs that use RTD and defaulting to pointing there?<br>
</blockquote><div><br></div><div>The <a href="http://docs.openstack.org">docs.openstack.org</a> site really feels more like end-user docs, where these will be "internal" developer docs. Using RTD makes sense for those. It's easy, supports multiple versions, and is one less thing for our infrastructure team to worry about as we spin out new libraries.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
My primary interest is in having the documentation readily and clearly available - there's methods and details that I simple don't know what they do, and writing better documentation into docstrings is usually how I solve that problem for myself. :-) How should I do so that stays with the project and makes that work most effectively available to all?<br>

<br>
- joe<br>
<div class="im HOEnZb"><br>
On Nov 13, 2012, at 11:56 AM, Mark McLoughlin <<a href="mailto:markmc@redhat.com">markmc@redhat.com</a>> wrote:<br>
> On Tue, 2012-11-13 at 07:02 -0800, James E. Blair wrote:<br>
>> Mark McLoughlin <<a href="mailto:markmc@redhat.com">markmc@redhat.com</a>> writes:<br>
>><br>
>>> When the API is ready for a library release, we either create a new<br>
>>> library that installs into the 'oslo' namespace package or add it to an<br>
>>> existing library. Either way, it moves out of oslo-incubator at that<br>
>>> point and switch to using it as a normal library API.<br>
>>><br>
>>> The point of calling the repo oslo-incubator is to reinforce the idea<br>
>>> that code isn't intended to live their forever. It's a stepping stone<br>
>>> towards a proper library release.<br>
>>><br>
>>> I think this will all become more obvious to everyone after we do our<br>
>>> first library release. We're starting with oslo-config once some last<br>
>>> minute things are wrapped up:<br>
>>><br>
>>>  <a href="https://github.com/markmc/oslo-config" target="_blank">https://github.com/markmc/oslo-config</a><br>
>><br>
>> Thanks for the clarification.  Your last link suggests some questions<br>
>> about the details of the process of splitting off a stable library from<br>
>> incubation.<br>
<br>
<br>
<br>
</div><div class="HOEnZb"><div class="h5">_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></div><br>