beehive-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Eddie ONeil <ekon...@gmail.com>
Subject Re: beehive documentation: maintaining docs from many releases -- was: Re: updating the beehive web site -- a two pronged approach
Date Tue, 16 Aug 2005 12:31:42 GMT
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 <kentaminator@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 <ekoneil@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 <steveh@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
> > >>>>>>
> > >>>>>>
> > >>>>>>
> > >>>>
> > >>>>
> > >>>>
> > >>>
> > >
> >
> >
>

Mime
View raw message