Mailing-List: contact dev-help@stdcxx.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@stdcxx.apache.org
Received-SPF: pass (athena.apache.org: domain of msebor@gmail.com designates
 209.85.198.233 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=message-id:date:from:user-agent:mime-version:to:subject:references
         :in-reply-to:content-type:content-transfer-encoding;
        b=INSfJbLbMtDhde9P3xZmCi3X//3MGgyY/u7Ix/5PbXfpJrW4iwgYuasTuIe8B/ZK7+
         C2w6puuOcTEddskZbfgZXQ5GRR/yMdB+kNv8rPgDhlRA5N2ves5JGWmn1DK2c+7G/cYB
         JQKqDEY2vI165sa95PaIXHyG2mMr+J/JXIoAc=
Message-ID: <48A4DC8E.1060505@gmail.com>
Date: Thu, 14 Aug 2008 19:31:58 -0600
From: Martin Sebor <msebor@gmail.com>
User-Agent: Thunderbird 2.0.0.16 (X11/20080723)
MIME-Version: 1.0
To: dev@stdcxx.apache.org
Subject: Re: Website Layout
References: <945707.1201827547692.JavaMail.jira@brutus>
 <63203.124.169.96.181.1201840274.squirrel@www.e-wire.net.au>
 <47A2B563.2010209@roguewave.com> <001f01c864ab$f3da62e0$0200a8c0@developer>
 <CFFDD219128FD94FB4F92B99F52D0A49010A3532@exchmail01.Blue.Roguewave.Com>
 <004101c867f2$16025fa0$0200a8c0@developer> <47A8DD67.5010205@roguewave.com>
 <005b01c8837b$4c72d7f0$0200a8c0@developer>
 <003901c8fa91$70a3e410$0200a8c0@developer> <48A0FA86.2090603@gmail.com>
 <002d01c8fc5e$655a20f0$0200a8c0@developer> <48A1DB05.9000501@gmail.com>
 <007b01c8fce7$16e217a0$0200a8c0@developer> <48A344D5.6060104@gmail.com>
 <002901c8fdfa$44ae8b00$0200a8c0@developer>
In-Reply-To: <002901c8fdfa$44ae8b00$0200a8c0@developer>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

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:msebor@gmail.com]
>> Sent: Thursday, 14 August 2008 6:32 AM
>> To: dev@stdcxx.apache.org
>> Subject: Re: Website Layout
>>
>> Gavin wrote:
>>>> -----Original Message-----
>>>> From: Martin Sebor [mailto:msebor@gmail.com]
>>>> Sent: Wednesday, 13 August 2008 4:49 AM
>>>> To: dev@stdcxx.apache.org
>>>> 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
> 
>