Re: Shiro API Documentation

[Craig L Russell]

Hi,

I am inclined to agree with Tamas.



Craig

On Sep 7, 2009, at 12:14 PM, Tamás Cservenák wrote:

From my experience, maven is great for getting something going pretty quickly but I haven't seen it to be flexible enough to run the entire site. Confluence is both easy to use and powerful and allows for some pretty nice customizations of the look and feel of the site.

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.


Thanks,
~t~


On Mon, Sep 7, 2009 at 6:05 PM, Salazar, Alexander <
salazar_a...@gsb.stanford.edu> wrote:

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.

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.


impressive how easy it makes building documentation into a site.


pros/cons.

Pros
1. Build many of the pages needed directly from your pom
2. Easy to keep documentation linked and synced

be in one place

the site
5. Easy to layout like other Apache projects which will lend
easy-of-navigation and more credibility to the site.

Cons

2. Not as malleable as HTML and CSS
3. Not as easy to edit content as a wiki

so it seems.

Attached's a screenshot of the basic site using the basic skin.

-Alex

-----Original Message-----
From: Salazar, Alexander [mailto:salazar_a...@gsb.stanford.edu]
Sent: Friday, September 04, 2009 2:10 PM
To: shiro-dev@incubator.apache.org
Subject: RE: Shiro API Documentation


maven site compared to the wiki as the main site.

-----Original Message-----

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 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 3. All the content would be in your src directory under site-- it would all 4. Templates/Skins are easy to build (kinda) and easy to apply throughout 1. Unique formatting sytanx for pages and skins (APT, FML, Velocity, etc) 4. To see any change to the site, the whole thing needs to be rebuilt-- or I'd be happy to help with the site but I'm not clear on the value of a From: les.hazlew...@anjinllc.com [mailto:les.hazlew...@anjinllc.com] On

Behalf Of Les Hazlewood
Sent: Friday, September 04, 2009 11:59 AM
To: shiro-dev@incubator.apache.org
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

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


wrote:

best way to reference build artifacts and static resources from within On Fri, Sep 4, 2009 at 1:59 PM, Craig L Russell <craig.russ...@sun.com >

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
<kalle.o.korho...@gmail.com> wrote:

On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
Alexander<salazar_a...@gsb.stanford.edu> 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

Les had whether there were any guidelines regarding publishing the

the contents.

Kalle

javadocs by default). I already had a thread on this topic, see "Plans to publish javadocs & Maven site continuously/nightly?". The question 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

Craig L Russell
Architect, Sun Java Enterprise System http://db.apache.org/jdo
408 276-5638 mailto:craig.russ...@sun.com
P.S. A good JDO? O, Gasp!

Craig L Russell
Architect, Sun Java Enterprise System http://db.apache.org/jdo
408 276-5638 mailto:craig.russ...@sun.com
P.S. A good JDO? O, Gasp!

smime.p7s
Description: S/MIME cryptographic signature