Web site & Javadoc

[Emmanuel Lécharny <el...@gmail.com>]

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 ?