Alright Gavin, thanks for your patience in discussing this.
If you can point me at your sources I'll generate the HTML
and commit the whole lot under
http://svn.apache.org/repos/asf/stdcxx/site/forrest
as you suggest, and work on replacing the existing site
with the generated docs.
Martin
Gavin wrote:
-----Original Message-----
From: Martin Sebor [mailto:[EMAIL PROTECTED]
Sent: Thursday, 14 August 2008 6:32 AM
To: [email protected]
Subject: Re: Website Layout
Gavin wrote:
-----Original Message-----
From: Martin Sebor [mailto:[EMAIL PROTECTED]
Sent: Wednesday, 13 August 2008 4:49 AM
To: [email protected]
Subject: Re: Website Layout
Gavin wrote:
<snip>
So whilst we are at this level of even-ness (?) it is a good time to
swap it
over and make it live. However, over the next day or two, I will add
developer docs on how to go about updating the site, altering/adding
pages
etc..
Let me know what you think.
Sounds like a plan.
I assume we'll commit just the Forrest sources into Subversion
and generate the site out of them on people.a.o using a cron
job, correct?
Well, I'm sure various projects do things in slightly different ways.
However I would not recommend doing any building on people.a.o , and is
not
necessary anyway.
This is how Forrest, xmlgraphics and a few others do it :-
1. Alter xdocs locally to your needs.
2. svn ci to get sources upto date in svn
3. locally run 'forrest -f publish.xml build'
4. locally run 'forrest -f publish.xml deploy'
5. /x1/www/stdcxx.apache.org svn up
That's the general gist, more fully,
Forrest stores its site source files in
http://svn.apache.org/repos/asf/forrest/trunk/site-author/
and the generated site docs go to
http://svn.apache.org/repos/asf/forrest/site/
A cronjob on p.a.o then runs svn up hourly to
/x1/www/forrest.apache.org
The hourly sync to eos/aurora then picks that up and your updated docs
are
then live.
Again, with xmlgraphics, site source files stored in
http://svn.apache.org/repos/asf/xmlgraphics/site/
and the generated site docs go to
http://svn.apache.org/repos/asf/xmlgraphics/site/deploy/
/x1/www/xmgraphics.apache.org is svn of that deploy location, no idea
how
often they run svn up or if it is done manually. Also no idea if they
use
forrestbot (steps 2 and 3) or whether they svn ci the generated site,
you'd
have to talk to Jeremias about that.
So , possibly 2 slightly different methods.
I'm happy to help show the way to Forrests' method. And of course I will
continue to be on this list for any help required afterwards. One thing
to
note for others listening, it is necessary to have Apache Forrest
installed
on your local machine in order to alter the xdocs, test locally, build
and
then deploy.
There is a renewed talk on infra lists about having a shared zone or
something else where projects can build sites using Forrest/Maven/Anakia
that would be installed on the zone, the idea I guess is that generated
source files would live there and be copied over to various projects
/x1/www/*.a.o/ area. I'm not sure how it would work exactly but I'm
following for now to see how it pans out, or how long it will take. Just
thought I'd mention it, in the meantime we need to do one of the above.
I assume you're referring to the thread on Automating parts of
the web site publishing process. I've seen the discussion but
haven't had time to follow it closely enough to benefit from
it.
So, here's how I see it for stdcxx :-
Have forrest and site source files where they are currently in
http://svn.apache.org/repos/asf/stdcxx/site/forrest/
Have the generated site files in
http://svn.apache.org/repos/asf/stdcxx/site/deploy/
and 'svn remove' the current content from /site/
The above structure will remove the nasty side effect you currently have
of
forrest source files viewable on the web
(http://stdcxx.apache.org/forrest/)
doesn't look good.
Then create a cronjob to svn up hourly (or whatever delay you prefer) to
update your /x1/www/stdcxx.apache.org with the updated site files.
That's about it for now, what do you think?
Thanks for the detailed info! The depot structure and the cron
job approach sound reasonable (we already have a cron job running
to periodically update the existing site). My only concern is the
requirement to run Forrest locally on each committer's machine.
I understand that.
Do you happen to know the other projects' rationale for checking
the generated sites into Subversion instead of generating their
sites directly on people.a.o?
Yes, Infra Policy.
It seems that since the site is
generated from sources that already are in Subversion there
should be no reason to version the generated HTML as well, and
being able to update the site without having to have Forrest
install seems like a significant advantage. But given that most
other projects do it differently I suspect I must be missing
some significant disadvantages of the "simpler" approach. Is
there concern with the overhead o projects running Forrest too
often?
Imagine 200+ projects all building their sites with
forrest/maven/anakia/whatever on p.a.o , all no doubt installing their own
copy too. The overhead would be massive if it were allowed.
Also, generated docs I guess are still files produced by ASF projects, they
would also differ in their content and structure to the source files. As
such having the history would be a benefit.
I'm just guessing at that last bit, what I do know is that infra currently
insists that
a) no projects to run builds on infra,
b) generated site docs are to be in svn.
So, unless you can change that, and perhaps until that infra thread produces
something - join in as a usecase if you think it worthwile, then I'd go with
my suggestion.
Those that don't contribute to the website docs wont need forrest.
fwiw if you used Maven or any other build tool you'd be in the same
situation.
FWIW, the way I originally set up this project was to generate
the Forrest site in:
http://people.apache.org/~sebor/stdcxx/forrest-site/
The cron job that does the updating is in:
/people.apache.org:/home/sebor/bin/update-site.sh
Well, I'm not saying remove it , but ...
At the end of the day, I've made my recommendation, its up to you guys how
you want to proceed.
I have Forrest installed of course so there is no problem with me applying
doc patches and generating the site, if one or two others are happy to have
Forrest on their systems locally, then we don't really have a problem.
Gav...
Martin
Gav...
--
Internal Virus Database is out-of-date.
Checked by AVG.
Version: 7.5.524 / Virus Database: 270.5.12 - Release Date: 8/3/2008 12:00
AM
