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 <[email protected]>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 <[email protected] > >wrote: > > > Why would this change affect docs with pypi? > > > > > > On Tue, Jul 23, 2013 at 2:51 PM, Dave Brondsema < > > [email protected]> 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 <[email protected] > >> >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.
