Open Stack

On Tue, Nov 13, 2012 at 5:36 PM, heckj <heckj at mac.com> wrote:

> 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?
>

The docs.openstack.org 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.


>
> 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.
>
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20121113/3dc306f1/attachment.html>