You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@beehive.apache.org by Eddie ONeil <ek...@gmail.com> on 2005/06/12 02:07:02 UTC
beehive documentation: maintaining docs from many releases -- was: Re: updating the beehive web site -- a two pronged approach
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:ekoneil@gmail.com]
> > >>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 <st...@bea.com> 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:ekoneil@gmail.com]
> > >>>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
> > >>>
> > >>>
> > >>>
> > >
> > >
> > >
> >
> >
>
Re: beehive documentation: maintaining docs from many releases -- was: Re: updating the beehive web site -- a two pronged approach
Posted by Eddie ONeil <ek...@gmail.com>.
Comments in-line...
On 8/17/05, Kenneth Tam <ke...@gmail.com> wrote:
> Right, I don't question that Forrest has real advantages, and for
> large amounts of content it's clearly a win -- but the
> version-independent site has been hovering around the ~20-25K worth of
> content for the past year, with almost all changes being small
> incremental diffs (like adding a new committer, adding FAQs, etc)..
> this leads me to ask whether the overhead is worth it. I totally see
> how Forrest helped with a large change like exiting the Incubator, but
> it seems like something on that scale is unlikely to happen to this
> content any time soon.
>
> That said, your point about being able to automate the nightly update
> of the current release docs leads me to suggest that we do the same
> for the site, which in my mind would smooth the path enough to make
> the use of Forrest for all content pretty much pain-free.
Yeah, I definitely understand your point about simplicity, but I also
think that you'll find Forrest pretty painless. And, it's just less
work for simply maintaining the site (not just the content).
>
> This makes a lot of sense -- it sounds like Forrest essentially always
> does a "clean" build (ie pretty much all files get re-written even if
> there are no changes in them). Given that, and the ability to
> automate the update process on the server so that the only time you'd
> have to login to the server and do the tarball management yourself is
> if you couldn't wait for the nightly update, I think life is good.
I think it's safer to always do a "clean", and when combined with API
Javadoc, it's just easier to always start from scratch (and doesn't
take that long). The way this would be automated would be to script
the "sftp" upload and then just run cron on the server to crack the
nightly tarballs. So, it's something a project committer can do and
is just something I need to roll into the nightly process.
For the released doc, doing this sftp / ssh a few times a year doesn't
seem that bad. :)
Eddie
But,
Re: beehive documentation: maintaining docs from many releases -- was: Re: updating the beehive web site -- a two pronged approach
Posted by Kenneth Tam <ke...@gmail.com>.
> Addressing Forrest first...Forrest is useful for both the site and
> release documentation for a rew reasons:
>
> ...
>
> It's not clear that these steps can get much simpler without removing
> Forrest entirely, which would (IMHO) be significantly more work in the
> long run.
Right, I don't question that Forrest has real advantages, and for
large amounts of content it's clearly a win -- but the
version-independent site has been hovering around the ~20-25K worth of
content for the past year, with almost all changes being small
incremental diffs (like adding a new committer, adding FAQs, etc)..
this leads me to ask whether the overhead is worth it. I totally see
how Forrest helped with a large change like exiting the Incubator, but
it seems like something on that scale is unlikely to happen to this
content any time soon.
That said, your point about being able to automate the nightly update
of the current release docs leads me to suggest that we do the same
for the site, which in my mind would smooth the path enough to make
the use of Forrest for all content pretty much pain-free.
> The reason to use SVN to manage the documentation is to enable easy
> updates on the Apache web servers, but I'd guess that the SVN commit
> of 32 MB of doc would take longer than the publishing steps below. :)
This makes a lot of sense -- it sounds like Forrest essentially always
does a "clean" build (ie pretty much all files get re-written even if
there are no changes in them). Given that, and the ability to
automate the update process on the server so that the only time you'd
have to login to the server and do the tarball management yourself is
if you couldn't wait for the nightly update, I think life is good.
Do you know who has the ability to set up the automation? Is that
something a project committer can do, or is it an infrastructure
thing?
Re: beehive documentation: maintaining docs from many releases -- was: Re: updating the beehive web site -- a two pronged approach
Posted by Eddie ONeil <ek...@gmail.com>.
Ken--
Addressing Forrest first...Forrest is useful for both the site and
release documentation for a rew reasons:
- it does link checking. Updating with Forrest right now, I'm very
comfortable that the site works and doesn't have dead links when it's
built and then made live.
- the Forrest "chrome" is something I'd rather not have to maintain.
Forrest is pretty good at managing the resources (images, CSS, etc)
that surround the site thus freeing authors to focus on the task of
adding content. I found this when unbranding from Incubator -- it was
really easy to just edit the skinconf.xml file and attach a new Apache
image to the "chrome" in the upper left-hand corner. Without this,
every single .html file in the website would have needed a manual
edit.
- in addition, the Forrest "chrome" helps with navigation including
tabs, nested / collapsible menus, copyrights, update times, CSS, and
feedback links
- several projects (Struts included) are moving their websites away
from raw HTML and onto Forrest because of things like the points
above. Given this, I'd assume that it's safe bet as an Apache tool
and will continue to evolve / improve.
The update process for the website is currently pretty simple.
Consider adding a news item; the steps for making this live would be:
1) edit docs/forrest/site/src/documentation/content/xdocs/index.xml
2) cd trunk/docs/forrest
3) ant build.site stage.site
(note, this does the Forrest build -- XHTML validation, link
checking, XHTML generation, skinning -- and then applies the new site
to the docs/forrest/www directory
4) svn commit www
5) ssh minotaur.apache.org
6) cd /www/beehive.apache.org
7) svn update
It's not clear that these steps can get much simpler without removing
Forrest entirely, which would (IMHO) be significantly more work in the
long run.
FWIW, I'd still like to move trunk/docs/forrest/site and
trunk/docs/forrest/www out of the trunk/ and into beehive/site. Just
haven't gotten around to doing that in the recent rework of the
documentation builds.
For the release builds, your suggestion was exactly what I proposed
to Steve back in June, but he convinced me otherwise because of the
management overhead related to evolving documentation and the size of
the doc kit in the SVN tree. :) The current doc kit is about 32 MB
with about 2k files, which isn't a small amount of stuff to check into
/ sync from SVN. And, hopefully, these numbers go up. In the case of
nightly documentation (which I'd like to have online), there are also
issues with refactoring the structure of the documentation / removing
content that would require either mass delete / re-add or surgery on
the doc tree to reflect on the website.
The reason to use SVN to manage the documentation is to enable easy
updates on the Apache web servers, but I'd guess that the SVN commit
of 32 MB of doc would take longer than the publishing steps below. :)
The current steps for adding release documentation are:
1) cd trunk/
2) ant -f distribution.xml build.release.docs
(this creates a sub-directory trunk/build/docs where the release
docs for the site are staged. also, I added this target today and
just haven't moved it up into the top-level build.xml file)
3) tar -cvf beehive-docs.tar trunk/build/docs
4) ... ftp beehive-docs.tar to minotaur.apache.org ...
5) ssh minotaur.apache.org
6) cd /www/beehive.apache.org/releases/<version>
7) tar -xvf beehive-docs.tar
For releases, this process happens infrequently, and for nightly
builds, it's totally automatable. Note, there's also a need to add a
new documentation link to the website, which is pretty simple -- look
at the v1m1 link in:
docs/forrest/site/src/documentation/content/xdocs/site.xml
With this setup, we've also got the ability to independently vary the
"chrome" around the releaes documentation and website.
Ultimately, IMHO, Forrest is a good tool for both release and site
documentation and the publishing processes seem pretty simple. It's
really not so painful to edit the Forrest doc. :)
Comments welcome...
Eddie
On 8/16/05, Kenneth Tam <ke...@gmail.com> wrote:
> > Actually, this is already done. :)
> >
> > Take a look at SVN checkins 227458, which broke the documentation
> > into two separate documentation roots for the site/ and release/, and
> > 230614, which checked a copy of the generated site into
> > docs/forrest/www.
> >
> > The current website at beehive.apache.org is running checked out of
> > docs/forrest/www, and the branches/v1/m1 line has been updated to
> > produce a doc kit that matches this structure.
>
> Actually I am proposing something a little different (the work you did
> to factor the version specific content from the version independent
> content is key):
>
> 1) For the version-independent content, I'm proposing that we consider
> cutting Forrest out of the picture altogether and just check in the
> raw HTML. It's not clear there's real value add in using Forrest
> given the kind of content that will remain version independent, and it
> would make things simpler/cleaner -- you wouldn't have to deal with
> building/staging for most tweaks, like updating news items etc. My
> main argument for this is that having a super smooth path to updating
> the site makes it more likely that such updates will happen :)
>
> 2) For the version-specific content (ie, the documentation for a
> specific version), I'm proposing that we keep Forrest and check in a
> copy of the generated content (a la what we're doing today with the
> version-independent content). This makes it easier to update the docs
> for the trunk/"currently in development".
>
> Here's a dir structure I think would work:
>
> beehive/site/www/ : content is source controlled; we initially
> populate it with the raw HTML of the version-independent content.
>
> beehive/trunk/docs/forrest/ : same as it is today, content is source
> controlled. Builds into build/.., and staging target copies the
> generated output to beehive/site/www/trunk.
>
> beehive/site/www/trunk/ : as a subdir of www, content is souce
> controlled. Initially populated by building
> beehive/trunk/docs/forrest, staging the result and submitting.
>
> beehive/site/www/<branch or version name> : peers of www/trunk exist
> for each interesting branch or version. Unless there are parallel
> lines of active development, these peers are unlikely to see much
> action.
>
> FWIW, I don't think it's that important that the "chrome" around the
> various version-specific documentation (aka "releases") be very
> similar to what's around the version-independent content (aka "the
> website"). I think we need to avoid gross clashes (like totally
> different colour/font schemes), but otherwise I don't think it's a big
> deal. Having a simpler update process seems more important to me.
>
> > There is a little quirky-ness with doing it this way, mostly related
> > to having duplicated images and dealing with tab names. I think it's
> > worth dealing with that for the time being as it's not easy to keep
> > the release and website content looking similar unless Forrest is used
> > to create them. Lots of projects at Apache are going this way --
> > checking the website in -- so I'd guess that at some point, they'll
> > have to solve some of the quirks with having two Forrest content
> > roots.
> >
> > The file trunk/docs/how_to_contribute_docs.txt has more information
> > about how this process works.
> >
> > Eddie
> >
> >
> >
> > On 8/16/05, Kenneth Tam <ke...@gmail.com> wrote:
> > > 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 <ek...@bea.com> 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:ekoneil@gmail.com]
> > > > >>>>>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 <st...@bea.com> 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:ekoneil@gmail.com]
> > > > >>>>>>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
> > > > >>>>>>
> > > > >>>>>>
> > > > >>>>>>
> > > > >>>>
> > > > >>>>
> > > > >>>>
> > > > >>>
> > > > >
> > > >
> > > >
> > >
> >
>
Re: beehive documentation: maintaining docs from many releases -- was: Re: updating the beehive web site -- a two pronged approach
Posted by Kenneth Tam <ke...@gmail.com>.
> Actually, this is already done. :)
>
> Take a look at SVN checkins 227458, which broke the documentation
> into two separate documentation roots for the site/ and release/, and
> 230614, which checked a copy of the generated site into
> docs/forrest/www.
>
> The current website at beehive.apache.org is running checked out of
> docs/forrest/www, and the branches/v1/m1 line has been updated to
> produce a doc kit that matches this structure.
Actually I am proposing something a little different (the work you did
to factor the version specific content from the version independent
content is key):
1) For the version-independent content, I'm proposing that we consider
cutting Forrest out of the picture altogether and just check in the
raw HTML. It's not clear there's real value add in using Forrest
given the kind of content that will remain version independent, and it
would make things simpler/cleaner -- you wouldn't have to deal with
building/staging for most tweaks, like updating news items etc. My
main argument for this is that having a super smooth path to updating
the site makes it more likely that such updates will happen :)
2) For the version-specific content (ie, the documentation for a
specific version), I'm proposing that we keep Forrest and check in a
copy of the generated content (a la what we're doing today with the
version-independent content). This makes it easier to update the docs
for the trunk/"currently in development".
Here's a dir structure I think would work:
beehive/site/www/ : content is source controlled; we initially
populate it with the raw HTML of the version-independent content.
beehive/trunk/docs/forrest/ : same as it is today, content is source
controlled. Builds into build/.., and staging target copies the
generated output to beehive/site/www/trunk.
beehive/site/www/trunk/ : as a subdir of www, content is souce
controlled. Initially populated by building
beehive/trunk/docs/forrest, staging the result and submitting.
beehive/site/www/<branch or version name> : peers of www/trunk exist
for each interesting branch or version. Unless there are parallel
lines of active development, these peers are unlikely to see much
action.
FWIW, I don't think it's that important that the "chrome" around the
various version-specific documentation (aka "releases") be very
similar to what's around the version-independent content (aka "the
website"). I think we need to avoid gross clashes (like totally
different colour/font schemes), but otherwise I don't think it's a big
deal. Having a simpler update process seems more important to me.
> There is a little quirky-ness with doing it this way, mostly related
> to having duplicated images and dealing with tab names. I think it's
> worth dealing with that for the time being as it's not easy to keep
> the release and website content looking similar unless Forrest is used
> to create them. Lots of projects at Apache are going this way --
> checking the website in -- so I'd guess that at some point, they'll
> have to solve some of the quirks with having two Forrest content
> roots.
>
> The file trunk/docs/how_to_contribute_docs.txt has more information
> about how this process works.
>
> Eddie
>
>
>
> On 8/16/05, Kenneth Tam <ke...@gmail.com> wrote:
> > 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 <ek...@bea.com> 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:ekoneil@gmail.com]
> > > >>>>>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 <st...@bea.com> 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:ekoneil@gmail.com]
> > > >>>>>>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
> > > >>>>>>
> > > >>>>>>
> > > >>>>>>
> > > >>>>
> > > >>>>
> > > >>>>
> > > >>>
> > > >
> > >
> > >
> >
>
Re: beehive documentation: maintaining docs from many releases -- was: Re: updating the beehive web site -- a two pronged approach
Posted by Eddie ONeil <ek...@gmail.com>.
Ken--
Actually, this is already done. :)
Take a look at SVN checkins 227458, which broke the documentation
into two separate documentation roots for the site/ and release/, and
230614, which checked a copy of the generated site into
docs/forrest/www.
The current website at beehive.apache.org is running checked out of
docs/forrest/www, and the branches/v1/m1 line has been updated to
produce a doc kit that matches this structure.
There is a little quirky-ness with doing it this way, mostly related
to having duplicated images and dealing with tab names. I think it's
worth dealing with that for the time being as it's not easy to keep
the release and website content looking similar unless Forrest is used
to create them. Lots of projects at Apache are going this way --
checking the website in -- so I'd guess that at some point, they'll
have to solve some of the quirks with having two Forrest content
roots.
The file trunk/docs/how_to_contribute_docs.txt has more information
about how this process works.
Eddie
On 8/16/05, Kenneth Tam <ke...@gmail.com> wrote:
> 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 <ek...@bea.com> 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:ekoneil@gmail.com]
> > >>>>>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 <st...@bea.com> 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:ekoneil@gmail.com]
> > >>>>>>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
> > >>>>>>
> > >>>>>>
> > >>>>>>
> > >>>>
> > >>>>
> > >>>>
> > >>>
> > >
> >
> >
>
Re: beehive documentation: maintaining docs from many releases -- was: Re: updating the beehive web site -- a two pronged approach
Posted by Kenneth Tam <ke...@gmail.com>.
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 <ek...@bea.com> 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:ekoneil@gmail.com]
> >>>>>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 <st...@bea.com> 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:ekoneil@gmail.com]
> >>>>>>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
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>
> >>>>
> >>>>
> >>>
> >
>
>
Re: beehive documentation: maintaining docs from many releases --
was: Re: updating the beehive web site -- a two pronged approach
Posted by Eddie O'Neil <ek...@bea.com>.
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:ekoneil@gmail.com]
>>>>>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 <st...@bea.com> 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:ekoneil@gmail.com]
>>>>>>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
>>>>>>
>>>>>>
>>>>>>
>>>>
>>>>
>>>>
>>>
>