You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by Christian Grobmeier <gr...@gmail.com> on 2013/09/04 10:08:45 UTC

Re: Documentation in general

Am 04.09.13 08:26, schrieb Lukasz Lenart:
> 2013/9/3 Steven Benitez <st...@gmail.com>:
>> I'm not sure that this would be a good fit for Struts2, but I'll throw the
>> idea out there anyway.
>>
>> On my current project, we needed a way to have an internal documentation
>> site and I am using Jekyll, Github's open source content generator (the
>> same engine that powers Github Pages). The actual documentation are stored
>> as markdown files in Git (could be in the S2 repository).
>>
>> http://jekyllrb.com/
> Good idea and we were talking about that - but first we must export
> all the docs from Confluence to markdown format, setup comments engine
> and so on - lot of work :-) But definitely is worth to engage as the
> current ApacheCMS/SvnPubSub mechanism is a bit painful when used with
> Confluence ;-) And thus allows contribute patches to documentation :-)
>
> Anyway, before we can start, docs must contain all the data - not to
> be spread throughout the source code (example snippets, tag reference)
I love Jekyll myself, +1 on that.

Can we export the docs in some way already? How can this be done?


>> A wiki may be better for our purposes, but I think that the barrier to
>> contribution needs to be re-worked. I've submitted patches to the code
>> before, but to contribute documentation I need to fill out a form, print
>> it, scan it, and email/fax it to Apache. Seems like more trouble than it's
>> worth, IMO.
> C'mon, it's just 5 sec! And opens doors to become committer :-)
>
>
> Regards


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org

Re: Documentation in general

Posted by Ken McWilliams <ke...@gmail.com>.
Thank you Lukasz,

I have a document saying I have a "Confluence"/cwiki.apache.org account:
registered with the email address ken.mcwilliams@gmail.com and the username
Quaternion.
Sounds good, I'll certainly have some questions regarding current document
structure, might want to document those too ;) one of the motivations was
the tag reference... the "evaluated" field is _always_ false!

Regards,

Ken McWilliams


On Tue, Feb 25, 2014 at 11:56 PM, Lukasz Lenart <lu...@apache.org>wrote:

> Great! Do you have user created in Confluence already? If no please
> create one and I will assign required rights. Another thing is that I
> want to move Getting Started [1] guide from Confluence to be part of
> our website. And as the website is in Subversion (powered by Jekyll)
> so you can simple prepare patches :-)
>
> [1] https://cwiki.apache.org/confluence/display/WW/Getting+Started
> [2] http://svn.apache.org/repos/asf/struts/site/trunk/
>
>
> Regards
> --
> Łukasz
> + 48 606 323 122 http://www.lenart.org.pl/
>
> 2014-02-25 23:26 GMT+01:00 Ken McWilliams <ke...@gmail.com>:
> > Hello Devs,
> >
> > I've finally filled out and submitted the ICLA and look forward to being
> > able to contribute to the documentation (wiki) also since the demos have
> > been moved to git I look forward to inspecting the demos and possibly
> > contributing there as well.
> >
> > "please advise the project PMC that your ICLA has been filed."
> > It has been filed for: Ken McWilliams.
> >
> > Regards,
> > Ken
> >
> >
> > On Wed, Sep 4, 2013 at 3:03 AM, Lukasz Lenart <lukaszlenart@apache.org
> >wrote:
> >
> >> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> >> > Am 04.09.13 10:21, schrieb Lukasz Lenart:
> >> >> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> >> >>> Can we export the docs in some way already? How can this be done?
> >> >> Now we export docs with CXF SiteExporter but that exports to pure
> html
> >> files.
> >> >>
> >> >>
> https://svn.apache.org/repos/asf/struts/struts2/trunk/assembly/pom.xml
> >> >>
> >> >> There are some tools/scripts that can help but they are spread over
> >> >> Apache Svn and mostly project specific. Anyway, first we must clean
> up
> >> >> Confluence before going we that or find a concept to use the same
> with
> >> >> new docs engine (include code snippets and autogenerated files)
> >> > Nice. The CXF-Exporter looks hackable:
> >> >
> >>
> https://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/
> >> >
> >> > Maybe we have a chance to cut off the html generation and replace it
> >> > with markdown.
> >> >
> >> > How is the "generate docs from javadoc" thing done (aka Snippets)? Is
> it
> >> > a Confluence feature?
> >>
> >> Yes, it's a Confluence feature, i.e.
> >>
> >>
> {snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.ParametersInterceptor}
> >>
> >> from
> >> https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14064
> >>
> >>
> >> Regards
> >> --
> >> Łukasz
> >> + 48 606 323 122 http://www.lenart.org.pl/
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> >> For additional commands, e-mail: dev-help@struts.apache.org
> >>
> >>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>

Re: Documentation in general

Posted by Lukasz Lenart <lu...@apache.org>.
Great! Do you have user created in Confluence already? If no please
create one and I will assign required rights. Another thing is that I
want to move Getting Started [1] guide from Confluence to be part of
our website. And as the website is in Subversion (powered by Jekyll)
so you can simple prepare patches :-)

[1] https://cwiki.apache.org/confluence/display/WW/Getting+Started
[2] http://svn.apache.org/repos/asf/struts/site/trunk/


Regards
-- 
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/

2014-02-25 23:26 GMT+01:00 Ken McWilliams <ke...@gmail.com>:
> Hello Devs,
>
> I've finally filled out and submitted the ICLA and look forward to being
> able to contribute to the documentation (wiki) also since the demos have
> been moved to git I look forward to inspecting the demos and possibly
> contributing there as well.
>
> "please advise the project PMC that your ICLA has been filed."
> It has been filed for: Ken McWilliams.
>
> Regards,
> Ken
>
>
> On Wed, Sep 4, 2013 at 3:03 AM, Lukasz Lenart <lu...@apache.org>wrote:
>
>> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>> > Am 04.09.13 10:21, schrieb Lukasz Lenart:
>> >> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>> >>> Can we export the docs in some way already? How can this be done?
>> >> Now we export docs with CXF SiteExporter but that exports to pure html
>> files.
>> >>
>> >> https://svn.apache.org/repos/asf/struts/struts2/trunk/assembly/pom.xml
>> >>
>> >> There are some tools/scripts that can help but they are spread over
>> >> Apache Svn and mostly project specific. Anyway, first we must clean up
>> >> Confluence before going we that or find a concept to use the same with
>> >> new docs engine (include code snippets and autogenerated files)
>> > Nice. The CXF-Exporter looks hackable:
>> >
>> https://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/
>> >
>> > Maybe we have a chance to cut off the html generation and replace it
>> > with markdown.
>> >
>> > How is the "generate docs from javadoc" thing done (aka Snippets)? Is it
>> > a Confluence feature?
>>
>> Yes, it's a Confluence feature, i.e.
>>
>> {snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.ParametersInterceptor}
>>
>> from
>> https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14064
>>
>>
>> Regards
>> --
>> Łukasz
>> + 48 606 323 122 http://www.lenart.org.pl/
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
>> For additional commands, e-mail: dev-help@struts.apache.org
>>
>>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org

Re: Documentation in general

Posted by Ken McWilliams <ke...@gmail.com>.
Hello Devs,

I've finally filled out and submitted the ICLA and look forward to being
able to contribute to the documentation (wiki) also since the demos have
been moved to git I look forward to inspecting the demos and possibly
contributing there as well.

"please advise the project PMC that your ICLA has been filed."
It has been filed for: Ken McWilliams.

Regards,
Ken


On Wed, Sep 4, 2013 at 3:03 AM, Lukasz Lenart <lu...@apache.org>wrote:

> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> > Am 04.09.13 10:21, schrieb Lukasz Lenart:
> >> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> >>> Can we export the docs in some way already? How can this be done?
> >> Now we export docs with CXF SiteExporter but that exports to pure html
> files.
> >>
> >> https://svn.apache.org/repos/asf/struts/struts2/trunk/assembly/pom.xml
> >>
> >> There are some tools/scripts that can help but they are spread over
> >> Apache Svn and mostly project specific. Anyway, first we must clean up
> >> Confluence before going we that or find a concept to use the same with
> >> new docs engine (include code snippets and autogenerated files)
> > Nice. The CXF-Exporter looks hackable:
> >
> https://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/
> >
> > Maybe we have a chance to cut off the html generation and replace it
> > with markdown.
> >
> > How is the "generate docs from javadoc" thing done (aka Snippets)? Is it
> > a Confluence feature?
>
> Yes, it's a Confluence feature, i.e.
>
> {snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.ParametersInterceptor}
>
> from
> https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14064
>
>
> Regards
> --
> Łukasz
> + 48 606 323 122 http://www.lenart.org.pl/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>

Re: Documentation in general

Posted by Lukasz Lenart <lu...@apache.org>.
2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> Am 04.09.13 10:21, schrieb Lukasz Lenart:
>> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>>> Can we export the docs in some way already? How can this be done?
>> Now we export docs with CXF SiteExporter but that exports to pure html files.
>>
>> https://svn.apache.org/repos/asf/struts/struts2/trunk/assembly/pom.xml
>>
>> There are some tools/scripts that can help but they are spread over
>> Apache Svn and mostly project specific. Anyway, first we must clean up
>> Confluence before going we that or find a concept to use the same with
>> new docs engine (include code snippets and autogenerated files)
> Nice. The CXF-Exporter looks hackable:
> https://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/
>
> Maybe we have a chance to cut off the html generation and replace it
> with markdown.
>
> How is the "generate docs from javadoc" thing done (aka Snippets)? Is it
> a Confluence feature?

Yes, it's a Confluence feature, i.e.
{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.ParametersInterceptor}

from https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14064


Regards
-- 
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org

Re: Documentation in general

Posted by Christian Grobmeier <gr...@gmail.com>.
Am 04.09.13 10:21, schrieb Lukasz Lenart:
> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>> Can we export the docs in some way already? How can this be done?
> Now we export docs with CXF SiteExporter but that exports to pure html files.
>
> https://svn.apache.org/repos/asf/struts/struts2/trunk/assembly/pom.xml
>
> There are some tools/scripts that can help but they are spread over
> Apache Svn and mostly project specific. Anyway, first we must clean up
> Confluence before going we that or find a concept to use the same with
> new docs engine (include code snippets and autogenerated files)
Nice. The CXF-Exporter looks hackable:
https://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/

Maybe we have a chance to cut off the html generation and replace it
with markdown.

How is the "generate docs from javadoc" thing done (aka Snippets)? Is it
a Confluence feature?

>
> Regards


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org

Re: Documentation in general

Posted by Lukasz Lenart <lu...@apache.org>.
2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> Can we export the docs in some way already? How can this be done?

Now we export docs with CXF SiteExporter but that exports to pure html files.

https://svn.apache.org/repos/asf/struts/struts2/trunk/assembly/pom.xml

There are some tools/scripts that can help but they are spread over
Apache Svn and mostly project specific. Anyway, first we must clean up
Confluence before going we that or find a concept to use the same with
new docs engine (include code snippets and autogenerated files)


Regards
-- 
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org