incubator-allura-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Brondsema <dbronds...@slashdotmedia.com>
Subject Re: Allura docs reorganization
Date Tue, 23 Jul 2013 19:16:39 GMT
I'm not saying its necessarily a problem to pull Allura/docs to ./docs,
just noting one result of that.  I think a lot of our narrative docs (e.g.
SCM setup, tracker importer, importers, etc) apply to the whole system and
not just the core Allura package, so I think it is fine to move it up a dir.


On Tue, Jul 23, 2013 at 3:04 PM, Cory Johns <cjohns@slashdotmedia.com>wrote:

> Oh, you're suggesting that Allura, as the "base" package, should contain
> the system-level docs.  I could set it up that way and have Allura/docs/ be
> the "base" doc folder and have other packages be relative to that, I think.
>
>
> On Tue, Jul 23, 2013 at 3:01 PM, Cory Johns <cjohns@slashdotmedia.com
> >wrote:
>
> > Why would this change affect docs with pypi?
> >
> >
> > On Tue, Jul 23, 2013 at 2:51 PM, Dave Brondsema <
> > dbrondsema@slashdotmedia.com> wrote:
> >
> >> Makes sense to me, assuming the configuration and post-build stuff isn't
> >> too difficult.
> >>
> >> Possible downside is that once we come up with a way to publish to pypi,
> >> then `pip install Allura` won't have the whole-system narrative docs
> with
> >> it.  But I don't think that's too big of a deal.  We've got other issues
> >> to
> >> resolve for publishing our individual packages separately anyway.
> >>
> >>
> >> On Tue, Jul 23, 2013 at 2:36 PM, Cory Johns <cjohns@slashdotmedia.com
> >> >wrote:
> >>
> >> > In adding docs for the new importer code, I'm considering reorganizing
> >> the
> >> > docs structure in Allura to make it easier to document the multiple
> >> > packages.
> >> >
> >> > I'm going to move most of the documentation that's currently under
> >> > Allura/docs/ up to a top-level docs/ folder, which will be the docs
> >> index
> >> > and place for any narrative and platform-wide docs.  Then, each
> package
> >> can
> >> > have a docs/ sub-directory for documentation specific to that package,
> >> > primarily API docs for the classes in that package (which are
> generated
> >> > from the doc strings).
> >> >
> >> > This will require building docs across multiple folders and doing some
> >> > post-build path restructuring of the generated artifacts, but would
> keep
> >> > the docs for a package within that package directory.
> >> >
> >> > Anyone have any comments, concerns, or objections on this restructure?
> >> >
> >> >
> >> > - Cory
> >> >
> >>
> >>
> >>
> >> --
> >> Dave Brondsema
> >> Principal Software Engineer - sourceforge.net
> >> Dice Holdings, Inc.
> >>
> >
> >
>



-- 
Dave Brondsema
Principal Software Engineer - sourceforge.net
Dice Holdings, Inc.

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message