Open Stack

Hey Mark,

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.

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 docs.openstack.org like we do with keystone, glance, nova, etc.?

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?

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?

- joe

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