Nice work Ronald - big fan of wiki as we use it here for a lot of our
project documentation.
Maybe I'm being dense here, but it's not immediately obvious how the
structure of the confluence Wiki pages map to the structure of the
generated web site e.g the main "index" page has a set of Children
underneath which don't seem to match exactly to the left hand index on
the generated web site page.
With a little bit of poking around, I think I figured which Wiki pages
map to which web site pages - but maybe there's a more obvious or
clearer way that the relationships could be shown so that it's easy for
others to find, edit, and add new pages?
-- Rob
[EMAIL PROTECTED] wrote:
Hello,
In this somewhat lengthy post I’d like to announce the Felix site Marcel
Offermans and I have created. I’d like to describe the problem’s we ran into
(most notably with maven) and the basic site setup.
First of all, the address of the site is http://incubator.apache.org/felix/
This page redirects you to the apache wiki site
(http://cwiki.apache.org/FELIX). The entire site is created using the wiki
(which, in editable form, can be found at
http://cwiki.apache.org/confluence/display/FELIX/). Whenever page is changed,
a static copy is exported as HTML, and saved on the url found above.
This export step supports Velocity templates, so that’s where we put our
template. The template contains the menu of the site.
But now, you may ask yourself, why didn’t we make the site using maven? Well,
first of all, the wiki already contains a lot of information and putting that
in subversion would be kind of impractical. In general, using a wiki makes it a
lot easier for people to contribute to the documentation, so we chose to use
that for all documents produced by humans. But we have setup maven to generate
code-based information like unit-test results, javadoc, etc. It uses the same
Velocity template so it integrates into the site nicely.
There are at the moment some issues with the site. Some of them have to do with
the modules there are in the Felix project, and the fact that we want to
display the information like javadoc, etc in an aggregated view. The maven
plugins have some problems creating these aggregated views for the maven
modules.
Maven cannot generate the javadoc. This section in the buildfile has been
commented out. Every time I tried to generate it, I got a maven error.
I didn’t really look into it, but I could not get the surefire reports
generated. This again has something to with the project’s modules.
And last of all, the JXR (the source cross-reference tool). This too has
probably something to do with the fact that modules are used.
Perhaps some of the maven guru’s present here can shine a light on these
issues. It might very well be something that I’m doing wrong :) For all of you
who want to give it a try: use mvn site:site site:deploy to generate local copy
(in target/site-deployed). Generating a site into staging does not work, that's
why we've redirected the deployed version to a local directory.
The site online at the moment is mostly compliant with the apache incubator
site-requirements (http://incubator.apache.org/guides/sites.html). However,
there are some things that have to be done to make it 100% compliant:
1) The javadoc problems have to be fixed, so it can be generated.
2) The list of current commiters has to be checked.
3) Some text in the Felix roadmap
4) Coding standards
5) A list of dependencies.
And that’s it :)
So, as a short summary:
Site address = http://incubator.apache.org/felix/
The site is built in confluence. Edit the wiki at
http://cwiki.apache.org/confluence/display/FELIX/Index
Whenever a page is changed, it is exported to
http://cwiki.apache.org/FELIX/index.html and styled using a Velocity template.
Maven is going to be used to generate source-based documentation.
All the best,
Ronald Spierenburg & Marcel Offermans
--
Ascert - Taking systems to the Edge
[EMAIL PROTECTED]
+44 (0)20 7488 3470
www.ascert.com
