Hi Martin, > -----Original Message----- > From: Martin Sebor [mailto:[EMAIL PROTECTED] > Sent: Friday, 15 August 2008 11:32 AM > To: [email protected] > Subject: Re: Website Layout > > Alright Gavin, thanks for your patience in discussing this.
No problem, > 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. I was working on it from your trunk, so I exported it and zipped it up as exported.zip in my home dir on people (gmcdonald). Just to recap, you should put those sources in /site/forrest/ and the generated html should end up /site/deploy/ or whatever names you want to call them. Let me know how you get on. Gav... > > 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 > > > > > > > -- > 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
