Hi, I would not recommend using (and tying to) maven-site-plugin.... You have plenty of better alternatives: http://xsite.codehaus.org/ or Confluence (either publishing it directly or for authoring only, and exporting + post-processing pages), etc. Maven Site plugin is generally good to have reports (Javadoc, coverage, etc) generated, but using it for main site is something I would not recommend.
Thanks, ~t~ On Mon, Sep 7, 2009 at 6:05 PM, Salazar, Alexander < [email protected]> wrote: > I'd like to get an opinion on this Maven site how you'd like to move > forward so that I can starting working on the Shiro site and web > documentation. > > Since I'm new to Maven, I took sometime this weekend to play with it and > its site plugin. Not sure if this project ever used it before but its > impressive how easy it makes building documentation into a site. > > Though I'm still not sure of the pros and cons for a wiki primary site, I > built out a basic maven-based primary site for shiro and submit to you these > pros/cons. > > Pros > 1. Build many of the pages needed directly from your pom > 2. Easy to keep documentation linked and synced > 3. All the content would be in your src directory under site-- it would all > be in one place > 4. Templates/Skins are easy to build (kinda) and easy to apply throughout > the site > 5. Easy to layout like other Apache projects which will lend > easy-of-navigation and more credibility to the site. > > Cons > 1. Unique formatting sytanx for pages and skins (APT, FML, Velocity, etc) > 2. Not as malleable as HTML and CSS > 3. Not as easy to edit content as a wiki > 4. To see any change to the site, the whole thing needs to be rebuilt-- or > so it seems. > > Attached's a screenshot of the basic site using the basic skin. > > -Alex > > -----Original Message----- > From: Salazar, Alexander [mailto:[email protected]] > Sent: Friday, September 04, 2009 2:10 PM > To: [email protected] > Subject: RE: Shiro API Documentation > > I'd be happy to help with the site but I'm not clear on the value of a > maven site compared to the wiki as the main site. > > -----Original Message----- > From: [email protected] [mailto:[email protected]] On > Behalf Of Les Hazlewood > Sent: Friday, September 04, 2009 11:59 AM > To: [email protected] > Subject: Re: Shiro API Documentation > > I personally like the idea of using the wiki as our primary content > mechanism, but I would like it to look better. I understand that's > not difficult to do - we'd just need to apply a site template. Alex, > is this something you'd be interested in helping with? > > But let's say that we have the wiki exporting properly - what is the > best way to reference build artifacts and static resources from within > the wiki (like the JavaDocs)? Would we just export the site wherever > we want and then link to it from within the wiki? Where would the > physical files reside? > > - Les > > On Fri, Sep 4, 2009 at 1:59 PM, Craig L Russell <[email protected]> > wrote: > > > > On Sep 4, 2009, at 7:26 AM, Les Hazlewood wrote: > > > >> Sure, I think that's a good idea. > >> > >> Mentors - where can this site be hosted and how do we automate the > >> push to that location? > > > > The project needs to decide whether to publish the Maven-generated site > as > > "The Shiro Site", or whether to use the confluence wiki as the official > > site. > > > > The place to publish the result is http://incubator.apache.org/shiro > > > > Look at http://incubator.apache.org/ki/ for what is currently being > done. > > > > Once the project decides on the strategy for generating content, > > infrastructure can help with the mechanical details of automatically > > generating and pushing the site live. > > > > Craig > >> > >> Thanks, > >> > >> Les > >> > >> On Fri, Sep 4, 2009 at 10:17 AM, Kalle Korhonen > >> <[email protected]> wrote: > >>> > >>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar, > >>> Alexander<[email protected]> wrote: > >>>> > >>>> Even though a 1.0 has not yet been released, I think it would be > helpful > >>>> to get to-date Shiro API documentation online and available. > >>>> According to Les, "Maven auto-generates not just the API > documentation, > >>>> but an entire site. However, we've only been using the wiki thus far. > We > >>>> would have to get the auto-export of this generated documentation set > up > >>>> based on the automated build process." > >>>> > >>>> What would be the best way to go about this? Do you agree that it > would > >>>> be valuable prior to the 1.0 release? > >>> > >>> The best way would be to publish the Maven site (it includes the > >>> javadocs by default). I already had a thread on this topic, see "Plans > >>> to publish javadocs & Maven site continuously/nightly?". The question > >>> Les had whether there were any guidelines regarding publishing the > >>> documentation while a project is still in incubator but no responses > >>> (though I know at least CXF was publishing all docs while in incubator > >>> so I don't think it's an issue). Once we know *where* we could publish > >>> the site, we could set up a Hudson job and then incrementally improve > >>> the contents. > >>> > >>> Kalle > >>> > > > > Craig L Russell > > Architect, Sun Java Enterprise System http://db.apache.org/jdo > > 408 276-5638 mailto:[email protected] > > P.S. A good JDO? O, Gasp! > > > > >
