Many sandbox projects have documentation. Some of this is in docbook,
other is anakia-source on the uima/site/uima-website project. These are
currently handled separately. I propose we change this so that the
majority of the documentation, including any specific web-page on the
main site, be hosted in the project.
Then, we can use automation to have the maven command mvn site:deploy
move the site to people.apache.org in the right place.
To support this, I'm adding a site distribution management section to
all poms which could be parents of a POM having web documents:
<!-- children POMs will add their artifactId to the URL below -->
<distributionManagement>
<site>
<id>uima-website</id>
<name>UIMA Website</name>
<url>${uimaWebsiteDistributionUrl}</url> <!-- set this var in your
settings.xml -->
</site>
</distributionManagement>
Maven has a convention of rewriting the values of <url> elements which
are inherited: it appends "/" and the artifactId.
Conventional values for uimaWebsiteDistributionUrl are:
- for testing: file:///c:/temp/localUimaSite
- for deployment to people: scp://people.apache.org/www/uima.apache.org/d
Having a "top-level" directory "d" will remind us where these came from,
and prevent collisions with our other process for updating the website,
which uses svn update. Making it a short name like "d" vs. "deployed"
means less clutter in urls that may be published which reference this
documentation.
If we go in this direction, I will change the docbook to output the
files it produces to target/site/docbkx.
Deploying to the website is something we would do after a release, to
update the documentation on the site. This also implies we follow the
normal conventions of just keeping the "current" documentation on the
website.
WDYT? -Marshall
