[jira] Created: (SHIRO-94) Update web pages to change JSecurity and Ki to Shiro

classic Classic list List threaded Threaded
24 messages Options
12
Reply | Threaded
Open this post in threaded view
|

[jira] Created: (SHIRO-94) Update web pages to change JSecurity and Ki to Shiro

JIRA jira@apache.org
Update web pages to change JSecurity and Ki to Shiro
-----------------------------------------------------

                 Key: SHIRO-94
                 URL: https://issues.apache.org/jira/browse/SHIRO-94
             Project: Shiro
          Issue Type: Task
            Reporter: Alex Salazar
            Priority: Minor


Update web pages to change JSecurity and Ki to Shiro

An Introduction to Ki (formerly JSecurity) - A Beginner's Tutorial by Bruce Phillips
Part 1-5

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Reply | Threaded
Open this post in threaded view
|

[jira] Resolved: (SHIRO-94) Update web pages to change JSecurity and Ki to Shiro

JIRA jira@apache.org

     [ https://issues.apache.org/jira/browse/SHIRO-94?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Les Hazlewood resolved SHIRO-94.
--------------------------------

       Resolution: Fixed
    Fix Version/s: 1.0

Updated the wiki page

> Update web pages to change JSecurity and Ki to Shiro
> -----------------------------------------------------
>
>                 Key: SHIRO-94
>                 URL: https://issues.apache.org/jira/browse/SHIRO-94
>             Project: Shiro
>          Issue Type: Task
>            Reporter: Alex Salazar
>            Priority: Minor
>             Fix For: 1.0
>
>
> Update web pages to change JSecurity and Ki to Shiro
> An Introduction to Ki (formerly JSecurity) - A Beginner's Tutorial by Bruce Phillips
> Part 1-5

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Reply | Threaded
Open this post in threaded view
|

[jira] Reopened: (SHIRO-94) Update web pages to change JSecurity and Ki to Shiro

JIRA jira@apache.org
In reply to this post by JIRA jira@apache.org

     [ https://issues.apache.org/jira/browse/SHIRO-94?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Alex Salazar reopened SHIRO-94:
-------------------------------


:)  It was more than text on the Article page.

The actual article uses Shiro, Ki, and Jsecurity all over the place.

I was planning on rebuilding the article(while maintaining Bruce as author) in the wiki since I can't edit Bruce's site.

> Update web pages to change JSecurity and Ki to Shiro
> -----------------------------------------------------
>
>                 Key: SHIRO-94
>                 URL: https://issues.apache.org/jira/browse/SHIRO-94
>             Project: Shiro
>          Issue Type: Task
>            Reporter: Alex Salazar
>            Priority: Minor
>             Fix For: 1.0
>
>
> Update web pages to change JSecurity and Ki to Shiro
> An Introduction to Ki (formerly JSecurity) - A Beginner's Tutorial by Bruce Phillips
> Part 1-5

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Reply | Threaded
Open this post in threaded view
|

[jira] Commented: (SHIRO-94) Update web pages to change JSecurity and Ki to Shiro

JIRA jira@apache.org
In reply to this post by JIRA jira@apache.org

    [ https://issues.apache.org/jira/browse/SHIRO-94?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12751260#action_12751260 ]

Alex Salazar commented on SHIRO-94:
-----------------------------------

Alternatively, I can edit the text and HTML and send to Bruce to update his site.  

> Update web pages to change JSecurity and Ki to Shiro
> -----------------------------------------------------
>
>                 Key: SHIRO-94
>                 URL: https://issues.apache.org/jira/browse/SHIRO-94
>             Project: Shiro
>          Issue Type: Task
>            Reporter: Alex Salazar
>            Priority: Minor
>             Fix For: 1.0
>
>
> Update web pages to change JSecurity and Ki to Shiro
> An Introduction to Ki (formerly JSecurity) - A Beginner's Tutorial by Bruce Phillips
> Part 1-5

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Reply | Threaded
Open this post in threaded view
|

[jira] Commented: (SHIRO-94) Update web pages to change JSecurity and Ki to Shiro

JIRA jira@apache.org
In reply to this post by JIRA jira@apache.org

    [ https://issues.apache.org/jira/browse/SHIRO-94?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12751286#action_12751286 ]

Les Hazlewood commented on SHIRO-94:
------------------------------------

Bruce is not a committer to the Shiro project - the Shiro team has no influence over what he has published or how he maintains it (even though we're very grateful for his efforts),  so the best thing to do is contact Bruce directly.  

But as this is a issue tracking system for the Apache Shiro team and for things which we can work on, I don't think this issue should remain open.  Thoughts?

> Update web pages to change JSecurity and Ki to Shiro
> -----------------------------------------------------
>
>                 Key: SHIRO-94
>                 URL: https://issues.apache.org/jira/browse/SHIRO-94
>             Project: Shiro
>          Issue Type: Task
>            Reporter: Alex Salazar
>            Priority: Minor
>             Fix For: 1.0
>
>
> Update web pages to change JSecurity and Ki to Shiro
> An Introduction to Ki (formerly JSecurity) - A Beginner's Tutorial by Bruce Phillips
> Part 1-5

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Reply | Threaded
Open this post in threaded view
|

[jira] Resolved: (SHIRO-94) Update web pages to change JSecurity and Ki to Shiro

JIRA jira@apache.org
In reply to this post by JIRA jira@apache.org

     [ https://issues.apache.org/jira/browse/SHIRO-94?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Alex Salazar resolved SHIRO-94.
-------------------------------

    Resolution: Fixed

> Update web pages to change JSecurity and Ki to Shiro
> -----------------------------------------------------
>
>                 Key: SHIRO-94
>                 URL: https://issues.apache.org/jira/browse/SHIRO-94
>             Project: Shiro
>          Issue Type: Task
>            Reporter: Alex Salazar
>            Priority: Minor
>             Fix For: 1.0
>
>
> Update web pages to change JSecurity and Ki to Shiro
> An Introduction to Ki (formerly JSecurity) - A Beginner's Tutorial by Bruce Phillips
> Part 1-5

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Reply | Threaded
Open this post in threaded view
|

[jira] Commented: (SHIRO-94) Update web pages to change JSecurity and Ki to Shiro

JIRA jira@apache.org
In reply to this post by JIRA jira@apache.org

    [ https://issues.apache.org/jira/browse/SHIRO-94?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12751324#action_12751324 ]

Alex Salazar commented on SHIRO-94:
-----------------------------------

Great point.  

 I'll close the issue and contact Bruce directly.

> Update web pages to change JSecurity and Ki to Shiro
> -----------------------------------------------------
>
>                 Key: SHIRO-94
>                 URL: https://issues.apache.org/jira/browse/SHIRO-94
>             Project: Shiro
>          Issue Type: Task
>            Reporter: Alex Salazar
>            Priority: Minor
>             Fix For: 1.0
>
>
> Update web pages to change JSecurity and Ki to Shiro
> An Introduction to Ki (formerly JSecurity) - A Beginner's Tutorial by Bruce Phillips
> Part 1-5

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Reply | Threaded
Open this post in threaded view
|

Shiro API Documentation

Salazar, Alexander
In reply to this post by JIRA jira@apache.org
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?

Alex
Reply | Threaded
Open this post in threaded view
|

Re: Shiro API Documentation

kaosko
On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
Alexander<[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: Shiro API Documentation

Les Hazlewood-2
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?

Thanks,

Les

On Fri, Sep 4, 2009 at 10:17 AM, Kalle Korhonen
<[hidden email]> wrote:

> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
> Alexander<[hidden email]> 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
>
Reply | Threaded
Open this post in threaded view
|

Re: Shiro API Documentation

kaosko
On Fri, Sep 4, 2009 at 7:26 AM, Les Hazlewood<[hidden email]> 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?

Maven can deploy the site via scp, dav, ftp, whatever we want.
Basically just another hudson job running weekly or even daily,
executing mvn site-deploy. That's for the snapshot documentation. For
releases, we need to decide whether we want to retain all
documentation for a particular version or publish documentation just
for the latest release (most open-source projects do the latter).

Kalle


> On Fri, Sep 4, 2009 at 10:17 AM, Kalle Korhonen
> <[hidden email]> wrote:
>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
>> Alexander<[hidden email]> 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
>>
>
Reply | Threaded
Open this post in threaded view
|

Re: Shiro API Documentation

papajdo
In reply to this post by Les Hazlewood-2

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
> <[hidden email]> wrote:
>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
>> Alexander<[hidden email]> 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:[hidden email]
P.S. A good JDO? O, Gasp!


smime.p7s (3K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Shiro API Documentation

Les Hazlewood-2
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 <[hidden email]> 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
>> <[hidden email]> wrote:
>>>
>>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
>>> Alexander<[hidden email]> 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:[hidden email]
> P.S. A good JDO? O, Gasp!
>
>
Reply | Threaded
Open this post in threaded view
|

RE: Shiro API Documentation

Salazar, Alexander
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: [hidden email] [mailto:[hidden email]] On Behalf Of Les Hazlewood
Sent: Friday, September 04, 2009 11:59 AM
To: [hidden email]
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 <[hidden email]> 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
>> <[hidden email]> wrote:
>>>
>>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
>>> Alexander<[hidden email]> 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:[hidden email]
> P.S. A good JDO? O, Gasp!
>
>
Reply | Threaded
Open this post in threaded view
|

RE: Shiro API Documentation

Salazar, Alexander
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:[hidden email]]
Sent: Friday, September 04, 2009 2:10 PM
To: [hidden email]
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: [hidden email] [mailto:[hidden email]] On Behalf Of Les Hazlewood
Sent: Friday, September 04, 2009 11:59 AM
To: [hidden email]
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 <[hidden email]> 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
>> <[hidden email]> wrote:
>>>
>>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
>>> Alexander<[hidden email]> 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:[hidden email]
> P.S. A good JDO? O, Gasp!
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Shiro API Documentation

Tamás Cservenák
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 <
[hidden email]> 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:[hidden email]]
> Sent: Friday, September 04, 2009 2:10 PM
> To: [hidden email]
> 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: [hidden email] [mailto:[hidden email]] On
> Behalf Of Les Hazlewood
> Sent: Friday, September 04, 2009 11:59 AM
> To: [hidden email]
> 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 <[hidden email]>
> 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
> >> <[hidden email]> wrote:
> >>>
> >>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
> >>> Alexander<[hidden email]> 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:[hidden email]
> > P.S. A good JDO? O, Gasp!
> >
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: Shiro API Documentation

papajdo
Hi,

I am inclined to agree with Tamas.

 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.

Craig

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

> 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 <
> [hidden email]> 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:[hidden email]]
>> Sent: Friday, September 04, 2009 2:10 PM
>> To: [hidden email]
>> 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: [hidden email]  
>> [mailto:[hidden email]] On
>> Behalf Of Les Hazlewood
>> Sent: Friday, September 04, 2009 11:59 AM
>> To: [hidden email]
>> 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 <[hidden email]
>> >
>> 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
>>>> <[hidden email]> wrote:
>>>>>
>>>>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
>>>>> Alexander<[hidden email]> 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:[hidden email]
>>> P.S. A good JDO? O, Gasp!
>>>
>>>
>>
Craig L Russell
Architect, Sun Java Enterprise System http://db.apache.org/jdo
408 276-5638 mailto:[hidden email]
P.S. A good JDO? O, Gasp!


smime.p7s (3K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Shiro API Documentation

Tamás Cservenák
Yup,
especially if you consider the upcoming maven3, and how it will redefine the
site plugin... The site plugin as is now -- in maven 2.x line -- was
generally a mistake. It is too coupled to core (or core is coupled to site
plugin because of reporting, depends on how you look at it), and did not
left place for any alternative reporting engine. This is what will change in
maven3 regarding to this plugin.

~t~

On Tue, Sep 8, 2009 at 5:57 AM, Craig L Russell <[hidden email]>wrote:

> Hi,
>
> I am inclined to agree with Tamas.
>
> 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.
>
> Craig
>
>
> On Sep 7, 2009, at 12:14 PM, Tamás Cservenák wrote:
>
>  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 <
>> [hidden email]> 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:[hidden email]]
>>> Sent: Friday, September 04, 2009 2:10 PM
>>> To: [hidden email]
>>> 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: [hidden email] [mailto:[hidden email]] On
>>> Behalf Of Les Hazlewood
>>> Sent: Friday, September 04, 2009 11:59 AM
>>> To: [hidden email]
>>> 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 <[hidden email]>
>>> 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
>>>>> <[hidden email]> wrote:
>>>>>
>>>>>>
>>>>>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
>>>>>> Alexander<[hidden email]> 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:[hidden email]
>>>> P.S. A good JDO? O, Gasp!
>>>>
>>>>
>>>>
>>>
> Craig L Russell
> Architect, Sun Java Enterprise System http://db.apache.org/jdo
> 408 276-5638 mailto:[hidden email]
> P.S. A good JDO? O, Gasp!
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Shiro API Documentation

kaosko
I've always maintained that the best option is to combine aspects of
both a static (Maven) site and a wiki. Actually I managed to do
exactly that for Trails project, seamlessly mixing Maven site and
Confluence content with the help of Codehaus' clever site layout
renderer and a heavily customized Maven site skin. Basically Codehaus'
site renderer pulls content snippets out of confluence and puts them
together as one page (sort of a smart server-side include). However,
Shiro's not a Codehaus project and Maven 3 is not here yet. In the
meantime, I agree that Confluence space is probably easier to use as
the main site, but nevertheless we need a Maven site destination to
publish the javadocs and the rest of useful generated content (data
pulled from pom, quality reports, etc.) and that we can do in the
short term. Agree?

Kalle


2009/9/8 Tamás Cservenák <[hidden email]>:

> Yup,
> especially if you consider the upcoming maven3, and how it will redefine the
> site plugin... The site plugin as is now -- in maven 2.x line -- was
> generally a mistake. It is too coupled to core (or core is coupled to site
> plugin because of reporting, depends on how you look at it), and did not
> left place for any alternative reporting engine. This is what will change in
> maven3 regarding to this plugin.
>
> ~t~
>
> On Tue, Sep 8, 2009 at 5:57 AM, Craig L Russell <[hidden email]>wrote:
>
>> Hi,
>>
>> I am inclined to agree with Tamas.
>>
>> 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.
>>
>> Craig
>>
>>
>> On Sep 7, 2009, at 12:14 PM, Tamás Cservenák wrote:
>>
>>  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 <
>>> [hidden email]> 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:[hidden email]]
>>>> Sent: Friday, September 04, 2009 2:10 PM
>>>> To: [hidden email]
>>>> 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: [hidden email] [mailto:[hidden email]] On
>>>> Behalf Of Les Hazlewood
>>>> Sent: Friday, September 04, 2009 11:59 AM
>>>> To: [hidden email]
>>>> 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 <[hidden email]>
>>>> 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
>>>>>> <[hidden email]> wrote:
>>>>>>
>>>>>>>
>>>>>>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
>>>>>>> Alexander<[hidden email]> 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:[hidden email]
>>>>> P.S. A good JDO? O, Gasp!
>>>>>
>>>>>
>>>>>
>>>>
>> Craig L Russell
>> Architect, Sun Java Enterprise System http://db.apache.org/jdo
>> 408 276-5638 mailto:[hidden email]
>> P.S. A good JDO? O, Gasp!
>>
>>
>
Reply | Threaded
Open this post in threaded view
|

Re: Shiro API Documentation

Les Hazlewood-2
In reply to this post by Salazar, Alexander
Hi Alex,

I don't think the mailing lists support attachments.  Can you show us
in a wiki page? (The wiki supports attachments).

- Les

On Mon, Sep 7, 2009 at 12:05 PM, Salazar, Alexander
<[hidden email]> 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:[hidden email]]
> Sent: Friday, September 04, 2009 2:10 PM
> To: [hidden email]
> 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: [hidden email] [mailto:[hidden email]] On Behalf Of Les Hazlewood
> Sent: Friday, September 04, 2009 11:59 AM
> To: [hidden email]
> 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 <[hidden email]> 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
>>> <[hidden email]> wrote:
>>>>
>>>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
>>>> Alexander<[hidden email]> 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:[hidden email]
>> P.S. A good JDO? O, Gasp!
>>
>>
>
12