Hi guys, this mail is just a quick expalantion about how we should proceed to export the Javadoc & XRef pages on the MINA website.
First of all, let's talk about the general mechanisms. - The web site is not updated live. In fact, when you are changing some content, it's done in three passes 1) you locally apply your changes 2) you commit those changes 3) if you see that the change is correct, you publish it. Ok, fine, but what does it mean ? The content is stored into a SVN based repository (http://svn.apache.org/repos/asf//mina/site/trunk/), so that everyone can check it out, and change it locally. When you ae done, you commit your change, and a hook will process them and push the resulting HTML generated pages onto a staging site. The staging site is available on http://mina.staging.apache.org. It's almost immediate (a matter of one or two seconds, usually), so you can immediately control your changes. Ok, now let's say you are good to go : you have to publish the site using a CMS (see http://www.apache.org/dev/cmsref.html#publishing for more information). What happens then is that *every single pages and content* from teh staging site is copied to the production site. More than that, if a directory/file is present on the production site, and not on the staging site, it will be REMOVED. Again : a directory/content present on production but not on staging WILL BE REMOVED from production. Ok ? Back to the javadoc and xref. They are generated locally, using mvn site, usually (assuming the maven config is correct, of course). The result can be quite big (megabytes of data, hundreds of pages and images). No, think : what if we push those data into the staging site ? Well, bingo : they will be duplicated on the production site. All of them. And it will take a hell lot of time. The solution : those pages are going to be pushed right away on the production site ! Yes, it's faster (despite the 10 minutes+ you might have to wait for everything to be committed there...). Does it fly ? Not that much, unless you complete one more step... Rememeber what I said about absent directories on the staging site and what's going to happen on the production site ? Yes, you do remember... "Holly F*CK??? Where are my javadoc/xeref pages gone ?" (it happend to me a couple of times...) So we have to tell the publish process to NOT do that, at all ! Easy : you have a dedicated text file that does the trick : http://svn.apache.org/repos/asf//mina/site/trunk/content/extpaths.txt It contains the list of directories *ON THE PRODUCTION SITE* that must not be deleted nor overwritten while copying the pages from the staging site. Here, we can see that it lists : # MINA mina-project/apidocs mina-project/testapidocs mina-project/xref mina-project/xref-test # SSHD sshd-project/apidocs On the production site, the following directories will not get deleted : https://svn.apache.org/repos/infra/websites/production/mina/content/mina-project/apidocs/ https://svn.apache.org/repos/infra/websites/production/mina/content/mina-project/testapidocs/ https://svn.apache.org/repos/infra/websites/production/mina/content/mina-project/xref/ https://svn.apache.org/repos/infra/websites/production/mina/content/mina-project/xref-test/ https://svn.apache.org/repos/infra/websites/production/mina/content/sshd-project/apidocs/ Btw, this is where you are going to commit the generated javadoc pages... Quite simple ? One more trick : if you add a link on this extpaths.txt file, be sure the directoy exists on the production site, otherwise you won't be allowed to publish... Hope it helps. Any question ?
