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! > >
