With the TLP change, it seems like a really good time to revisit this.. I'm a little confused over where things are? I gather from the thread that Forrest essentially has problems with multiple source roots.. has the following (somewhat naive) approach been debated?:
Keep the core site content (home page, nav links to version-specific content, infrastructure info, mailing lists, etc) as raw HTML checked into svn as a peer of trunk (e.g. "beehive/core-site". Continue to use Forrest to build/maintain version-specific content. A Forrest site would potentially exist for every branch, including trunk. We'd manually edit content in the core site to specify links to whatever version-specific sites we want to be serve out. Note this says nothing about how the live site is updated, just how the source content is version control managed. I like the idea of having a copy of the "built" version-specific content checked into each branch (ie, "beehive/trunk/docs/publish"), and then having the live server keep a checked out copy of each branch's docs (as well as the core site). On 7/21/05, Eddie O'Neil <[EMAIL PROTECTED]> wrote: > All-- > > Given that we're en route to leaving incubation and doing a Beehive > 1.0 release, the need to maintain multiple concurrent versions of > documentation is growing. > > I'm starting to refactor the trunk/docs/ directory to split the docs > into two parts: > > - site docs (committers, mailing lists, release links, etc) > - release docs (v1m1, v1, etc) > > Should have the first part of this done today by turning: > > trunk/docs/forrest/src/documentation/content/xdocs/ > > into a directory structured as: > > trunk/docs/forrest/src/documentation/content/xdocs/ > index.xml > site.xml > tabs.xml > downloads.xml > ...and so on... > release/ > pageflow/ > controls/ > system-controls/ > wsm/ > index.xml > > where release/ contains the docs for a given Beehive source line in SVN. > > This is necessary work but isn't sufficient to break the release and > site docs apart, so we should continue the discussion below if anyone > has additional input. The next step would be to move the site > documentation (index.xml, site.xml, downloads.xml, mailinglists.xml, > etc) into a site/ directory that is peer to trunk/ for easier versioning > / updating. > > Just wanted to let everyone know the work is starting. > > :) > > Eddie > > > > > Eddie ONeil wrote: > > This fork of this discussion is meant to address the issues and > > requirements around maintaining multiple versions of the Beehive > > documentation on the website at once. Today, there isn't an easy way > > to do this. > > > > The general proposal is at the bottom of this thread which includes > > Steve's responses. > > > > Eddie > > > > > > > > > >>>>>More concerns about (2): > >>>>>------------------------ > >>>>> > >>>>>Just to make sure I understand proposal (2), let me restate it: > >>>>> > >>>>> We should make a distinction between the release-dependent and > >>>>> release-independent docs. > >>>>> Release-dependent docs include the majority of topics like the user > >>>>> guides, tutorials, etc. > >>>>> Release-independent docs include the more static parts of the site, > >>>>> like the download page, > >>>>> mailing-list page, etc. > >>>>> The release-independent docs should be moved up a level to > >>>>> beehive/site, where Forrest will > >>>>> treat them like a relatively static site template. > >>>>> > >>>>>That's my restatement of proposal (2). If I've misunderstood it, stop > >>>>>now, and set me straight. > >>>>> > >>>>>If I have restated (2) correctly, I don't think that Forrest can handle > >>>>>it. Even if we can find a way for Forrest to handle and build against > >>>>>XML pages in two disparate directories, there are still other problems. > >>>>> > >>>>> > >>>>> > >>>> > >>>>Hm. Guess the question I'd ask here is this -- why is this a problem > >>>>for Forrest? We need to move the doc infrastructure to a place where > >>>>this is possible (note, these are hypothetical release numbers): > >>>> > >>>>beehive/ > >>>> branches/ > >>>> v1/ > >>>> v1.0/ > >>>> v1.1/ > >>>> v1.2/ > >>>> > >>>>which will result in a website that looks like: > >>>> > >>>> beehive/ > >>>> <core-site> > >>>> releases/ > >>>> v1.0/ > >>>> v1.1/ > >>>> v1.2/ > >>>> nightly/ > >>>> > >>>>where the v1.0, v1.1, v1.2 docs are generated from the branches/ > >>>>directory and nightly/ comes from trunk/. Currently, we don't seem to > >>>>have a clean way to do this because the entire site is re-generated > >>> > >>>>from the current release. So, things like the downloads, mailinglist, > >>> > >>>>and other version agnostic content comes from the site generated by > >>>>the most recent release. If a committer wants to add a "news" bullet, > >>>>post v1/m1, they've got to re-generate the site from the branch. > >>>> > >>>>Seems that it'd be easier to make a change to the Forrest XML file, > >>>>rebuild the version-agnostic content and update a single file... > >>>> > >>>> > >>>> > >>>> > >>>>>It is just difficult, in principle, to make a division between > >>>>>non-versioned parts of a doc set and versioned parts. For example, take > >>>>>the download page. If we make it a non-versioned part of the doc set, > >>>>>really a common, templated element to any doc set, then, how do we > >>>>>handle regeneration of an older version of the doc? Suppose we need to > >>>>>regenerate version 1: Do we included the download page, with its > >>>>>reference/link to version 2? > >>>>> > >>>>> > >>>> > >>>>To me the download page isn't something that needs to branch with the > >>>>source tree -- it would already be versioned in SVN and if we needed > >>>>an older version of the doc, we'd just sync back to an older SVN > >>>>version fo the file. > >>>> > >>>>Is there any way to assemble documentation generated by multiple > >>>>Forrest runs? Seems that if we're ever to support multiple versions > >>>>of the documentation that we'll need to be able to do this. If it's > >>>>possible, we can just go low-tech and checkin the version-agnostic > >>>>parts of the site and generate the doc for each release and copy it as > >>>>we do today. > >>>> > >>>> > >>>> > >>>> > >>>> > >>>> > >>>> > >>>>>All that said, I don't really have any brilliant ideas right now to deal > >>>>>with the pain that is coming our way as the versions of the docs start > >>>>>to proliferate. > >>>>> > >>>>>Maybe we need a script on the live site server that can run the doc > >>>>>targets and post the results? That way you won't need to run processes > >>>>>on two different machines. > >>>>> > >>>>>-steveh. > >>>>> > >>>>> > >>>>>-----Original Message----- > >>>>>From: Eddie ONeil [mailto:[EMAIL PROTECTED] > >>>>>Sent: Wednesday, June 08, 2005 2:22 PM > >>>>>To: Beehive Developers > >>>>>Subject: Re: updating the beehive web site -- a two pronged approach > >>>>> > >>>>> > >>>>>Steve-- > >>>>> > >>>>> Comments in line. > >>>>> > >>>>>Eddie > >>>>> > >>>>>On 6/8/05, Steve Hanson <[EMAIL PROTECTED]> wrote: > >>>>> > >>>>> > >>>>> > >>>>>>Hi all: > >>>>>> > >>>>>>Concerns and questions concerning (1): > >>>>>> > >>>>>>A system very similar to proposal (1) was in place for the v1-alpha > >>>>>>release. > >>>>>>One complaint about it at the time was that Javadoc-generated HTML > >>>>>>pages were being checked in to SVN. I am not sure how the current > >>>>>>proposal (1) avoids this drawback. > >>>>>> > >>>>>> > >>>>> > >>>>>You're correct -- the Javadoc is checked into SVN, but it's done so in > >>>>>a location like: > >>>>> > >>>>> beehive/ > >>>>> site/ > >>>>> publish/ > >>>>> ... > >>>>> > >>>>>which keeps it entirely out of the beehive/trunk directory. As I > >>>>>recall, keeping the Javadoc in trunk/ was the issue as we were always > >>>>>sync-ing updates. > >>>>> > >>>>>The difference here is that it's up at the beehive/site/... level > >>>>>which devs don't usually need to sync. > >>>>> > >>>>> > >>>>> > >>>>> > >>>>>>One question: Are we going to be checking in different doc sets for > >>>>>>each released version of Beehive, so that the tree would look > >>>>>>(something) like?: > >>>>>> > >>>>>>beehive > >>>>>> site > >>>>>> archives > >>>>>> v1 > >>>>>> v2 > >>>>>> current > >>>>>> v3 > >>>>>> > >>>>>> > >>>>>> > >>>>> > >>>>>In the long run, yes. This would make it *significantly* easier to > >>>>>keep the alpha, beta, m1, etc docs on the site and allow them to be > >>>>>updateable independently. > >>>>> > >>>>> > >>>>> > >>>>> > >>>>>>Concerns about (2): > >>>>>> > >>>>>>This proposal sounds like it would break Forrest. Forrest is looking > >>>>>>for one directory that contains the XML source files: I doubt it can > >>>>>>handle a disparate set of directories. Runnng Forrest mulitple times > >>>>>>and slapping the genered HTML together afterwards won't work either, > >>>>>>because Forrest needs to do link checking and build a single TOC. > >>>>>> > >>>>>> > >>>>>> > >>>>> > >>>>>Actually, I don't think it breaks Forrest if to generate the entire > >>>>>doc-kit, Forrest runs multiple times. For example, to update the > >>>>>documentation for a nightly, we'd do something like this: > >>>>> > >>>>>- build a nightly distribution from trunk/ > >>>>>- copy the documentation from trunk/build/dist/... up to > >>>>>site/publish/docs/nightly/... > >>>>>- svn commit the site/publish/docs/nightly directory > >>>>>- svn checkout on the live-site to refresh the web site > >>>>> > >>>>>Make sense? If I'm nuts, let me know. Just trying to lower the bar > >>>>>for updating the site and for allowing us to keep multiple copies of > >>>>>the doc on the site at once. > >>>>> > >>>>> > >>>>> > >>>>> > >>>>> > >>>>>>Craig R. McClanahan: I know that you have talked about these very > >>>>>>issues in Struts...do you have any insights here? > >>>>>> > >>>>>>-steve h. > >>>>>> > >>>>>> > >>>>>> > >>>>>> > >>>>>>-----Original Message----- > >>>>>>From: Eddie ONeil [mailto:[EMAIL PROTECTED] > >>>>>>Sent: Tuesday, June 07, 2005 8:05 PM > >>>>>>To: Beehive Developers > >>>>>>Subject: updating the beehive web site -- a two pronged approach > >>>>>> > >>>>>> > >>>>>>All-- > >>>>>> > >>>>>> After having worked on the Beehive website some in the last couple > >>>>>>of days, I've got a couple of suggestions for how we can make this > >>>>>>process significantly easier. The approach has two parts... The > >>>>>>first is the most (immediately) important. > >>>>>> > >>>>>>1) check the generated website into beehive/site in a read-only part > >>>>>>of SVN. This would allow committers to generate the website, check it > >>>>>>into SVN, and then check it out on the server. This process avoids > >>>>>>the generation and "scp" of a .zip file to the server and then the > >>>>>>"ssh" to crack the .zip file. To update the site, just run "svn > >>>>>>update" on the live site. This also makes it easier to roll back > >>>>>>after a failed change. > >>>>>> > >>>>>>2) the next step would be to decouple the release-independent content > >>>>>>of the site from the release-dependent documentation. This would move > >>>>>>things like the links to the mailinglists, downloads page, news page, > >>>>>>etc out of trunk/ and up a level so that it's versioned independently > >>>>>>of the versions of Beehive. This is checked into something like: > >>>>>> > >>>>>>beehive/ > >>>>>> site/ > >>>>>> author/ -- location for the content in the tree > >>>>>> publish/ -- location of the generated site > >>>>>> > >>>>>>Then, the release documentation can be generated, copied up to > >>>>>>publish/, checked into the tree, and "svn update"ed on the live site. > >>>>>> > >>>>>>Step (1) is something we can do now and would make updating the site > >>>>>>quite easy. Step (2) is something we can do longer term but would > >>>>>>decouple the release documentation from the more static website. > >>>>>> > >>>>>> Thoughts? > >>>>>> > >>>>>>Eddie > >>>>>> > >>>>>> > >>>>>> > >>>> > >>>> > >>>> > >>> > > > >
