Re: TOMEE-2341 - TomEE Site Generator

[David Blevins]

> On Jun 28, 2020, at 11:08 PM, David Blevins  wrote:
> 
> When we used the Apache CMS we had an extension that would basically grep the 
> source for the example and automatically append this list of links, see "APIs 
> Used" at the bottom:
> 
> - http://tomee.apache.org/examples-trunk/cdi-request-scope/README.html
> 
> The improvement part is since we are aggregating and publishing all the 
> Jakarta EE and MicroProfile javadocs on the TomEE website, let's link to 
> those Javadocs and while we're at it make them link back to the example.

I gave this another push to get it over the finish line and it feels really 
great.  I've been taking baby steps towards this for a long time.

= APIs Used

At the bottom of every example page there is an "APIs Used" section that links 
to any javadoc we have in our site that could apply to the example.  For 
example the Simple Singleton example:

 - http://tomee.staging.apache.org/tomee-9.0/examples/simple-singleton.html

Has a link to this Javadoc page:

 - http://tomee.staging.apache.org/jakartaee-9.0/javadoc/jakarta/ejb/Lock.html


= @examples Javadoc tag

On the page above we see there are now three new sections "Examples (en):", 
"Examples (es):" and "Examples (en):"  We're getting these by putting a custom 
javadoc tag (@example.en, @example.es, @example.pt) in the applicable java 
files before we generate the Javadoc.

There's logic to pick only the most recent version of the example.  There's 
also logic to sort the examples list so that the examples with the largest 
README.adoc are first.

With these two features you can bounce back and forth between examples and 
javadocs at will.


= Covers all APIs

As mentioned it works for any javadoc we publish.  Currently we publish javadoc 
for TomEE, Jakarta EE 8, Jakarta EE 9 and MicroProfile 2.

Some Jakarta EE 9 APIs we have examples for:

 - 
http://tomee.staging.apache.org/jakartaee-9.0/javadoc/jakarta/json/bind/Jsonb.html
 - 
http://tomee.staging.apache.org/jakartaee-9.0/javadoc/jakarta/ws/rs/PathParam.html
 - 
http://tomee.staging.apache.org/jakartaee-9.0/javadoc/jakarta/ejb/Startup.html

Some Jakarta EE 9 APIs we have examples for:

 - 
http://tomee.staging.apache.org/jakartaee-8.0/javadoc/javax/jms/MessageListener.html
 - 
http://tomee.staging.apache.org/jakartaee-8.0/javadoc/javax/persistence/EntityManager.html
 - 
http://tomee.staging.apache.org/jakartaee-8.0/javadoc/javax/ejb/ActivationConfigProperty.html

Some MicroProfile 2 APIs we have examples for:

 - 
http://tomee.staging.apache.org/microprofile-2.0/javadoc/org/eclipse/microprofile/health/HealthCheck.html
 - 
http://tomee.staging.apache.org/microprofile-2.0/javadoc/org/eclipse/microprofile/config/inject/ConfigProperty.html
 - 
http://tomee.staging.apache.org/microprofile-2.0/javadoc/org/eclipse/microprofile/metrics/annotation/Gauge.html

And of course we are using various TomEE APIs in our examples and those are 
marked up too:

 - 
http://tomee.staging.apache.org/tomee-9.0/javadoc/org/apache/openejb/junit/ApplicationComposer.html
 - 
http://tomee.staging.apache.org/tomee-9.0/javadoc/org/apache/openejb/testing/Module.html
 - 
http://tomee.staging.apache.org/tomee-9.0/javadoc/org/apache/openejb/jee/EjbJar.html


= Fancy icon for each Javadoc

And because I like these kinds of details, notice each Javadoc has a favicon 
with the appropriate logo.  The Jakarta stuff uses the sailboat, the 
MicroProfile javadocs use the 'M' logo, and of course the TomEE stuff uses the 
feather.


-David



smime.p7s
Description: S/MIME cryptographic signature

Re: TOMEE-2341 - TomEE Site Generator

[Willes Reis]

Hi David Blevins,

After reading all of the considerations, it seems we have a bunch of
objectives at stake :)
The comments are on below each block quotation.

> The most exciting of the tickets that I've really been dying to work on
is https://issues.apache.org/jira/browse/TOMEE-2346 which is basically to
1) restore an old feature and 2) improve while we're at it.
>
> When we used the Apache CMS we had an extension that would basically grep
the source for the example and automatically append this list of links, see
"APIs Used" at the bottom:
>
> - http://tomee.apache.org/examples-trunk/cdi-request-scope/README.html
>
> The improvement part is since we are aggregating and publishing all the
Jakarta EE and MicroProfile javadocs on the TomEE website, let's link to
those Javadocs and while we're at it make them link back > to the example.
>
> Short history of the site generator is Romain wrote it in 2016.  I picked
it up in Dec 2018 when he stopped working on it.  As I know from my own
experience it takes a bit to digest, I've gone ahead and wrote the basic
plumbing so we're right up close to the actual problem and you have a
better chance at helping.  Here's that diff:
>
> -
https://github.com/apache/tomee-site-generator/commit/dec4194bc77ca5eb2a1dcf36bb43a51bc4b5cb84

This knowledge is already great as a starting point.

> I think the smallest step into the code for you would be to implement
this class and get this test case to run:
>
> -
https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/SeeLinks.java#L26
> -
https://github.com/apache/tomee-site-generator/blob/master/src/test/java/org/apache/tomee/website/SeeLinksTest.java#L28

I agree with you, I will start with your suggestion working on SeeLinks
and, from there, I will settle in well to the project.

> Once that is implemented, we should magically start seeing links show up
in the correct Javadocs.

I keep thinking... Here it has a generator of javadocs as "cross
navigation" that cross resources between document api and examples
involved, bringing to users a navigation in a friendly way.
I have already issues assigned to me, but you can assign this to me as
well, if someone is not going to work on it soon, of course.

Thanks for your attention!
Willes

Em seg., 29 de jun. de 2020 às 03:08, David Blevins 
escreveu:

> > On Jun 27, 2020, at 10:15 PM, Willes Reis  wrote:
> >
> > Looking at the JIRA issue
> https://issues.apache.org/jira/browse/TOMEE-2341 on
> > which you are the reporter, I realized that there are 5 sub-tasks (2
> closed
> > / 3 open) and I would like to help with something in this, but I don't
> know
> > if the proposal is still valid? If ok, could you please explain the
> > expectations?
> >
> > Any feedback is appreciated.
>
> Hi Willes!
>
> Absolutely.  Any collaboration in this area is definitely welcome.  The
> most exciting of the tickets that I've really been dying to work on is
> https://issues.apache.org/jira/browse/TOMEE-2346 which is basically to 1)
> restore an old feature and 2) improve while we're at it.
>
> When we used the Apache CMS we had an extension that would basically grep
> the source for the example and automatically append this list of links, see
> "APIs Used" at the bottom:
>
>  - http://tomee.apache.org/examples-trunk/cdi-request-scope/README.html
>
> The improvement part is since we are aggregating and publishing all the
> Jakarta EE and MicroProfile javadocs on the TomEE website, let's link to
> those Javadocs and while we're at it make them link back to the example.
>
> Short history of the site generator is Romain wrote it in 2016.  I picked
> it up in Dec 2018 when he stopped working on it.  As I know from my own
> experience it takes a bit to digest, I've gone ahead and wrote the basic
> plumbing so we're right up close to the actual problem and you have a
> better chance at helping.  Here's that diff:
>
>  -
> https://github.com/apache/tomee-site-generator/commit/dec4194bc77ca5eb2a1dcf36bb43a51bc4b5cb84
>
> I think the smallest step into the code for you would be to implement this
> class and get this test case to run:
>
>  -
> https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/SeeLinks.java#L26
>  -
> https://github.com/apache/tomee-site-generator/blob/master/src/test/java/org/apache/tomee/website/SeeLinksTest.java#L28
>
> Once that is implemented, we should magically start seeing links show up
> in the correct Javadocs.
>
> I suspect we'll go back and forth a few times hammering out issues.  Once
> that part is done we can move to the part of adding links in the example
> itself.
>
> If we can nail those two things, we're done with TOMEE-2346 :)
>
> Don't hesitate to ask questions on how to build/run the project.  There is
> slight documentation there, but it can always be better.  If you struggle
> for more than a half-hour or so, shoot off an email.  Definitely do not
> spend several hours stuck on something 

Re: TOMEE-2341 - TomEE Site Generator

[David Blevins]

> On Jun 30, 2020, at 10:48 AM, Willes Reis  wrote:
> 
>> Hi Willes, looks like you grabbed TOMEE-55 and sounds like you might have
> been intending to reach out to David Jencks.
> 
>> If you do want to work on TOMEE-2346 let me know, otherwise I'll leave it
> unassigned.
> 
> Hi David Blevins,
> 
> I apologize for not replying to your considerations yet, but I did
> understand that it is a different person :)
> These are valuable considerations, but I could not reply at same time for
> being too late to me.
> As soon as possible I will reply to you.

Perfectly ok.  I'm sensitive it's easier to say yes than no.

I went and created a bunch of code and assigned an issue to you when you had 
only asked for information.  That put you in a situation where the only options 
are silence or "no". Neither are great options.  Sorry for that -- I get 
excited :)

Love any thoughts you have and the conversation is yours to drive.


-David

Re: TOMEE-2341 - TomEE Site Generator

[Willes Reis]

> Hi Willes, looks like you grabbed TOMEE-55 and sounds like you might have
been intending to reach out to David Jencks.

> If you do want to work on TOMEE-2346 let me know, otherwise I'll leave it
unassigned.

Hi David Blevins,

I apologize for not replying to your considerations yet, but I did
understand that it is a different person :)
These are valuable considerations, but I could not reply at same time for
being too late to me.
As soon as possible I will reply to you.

Thanks. See you.
Willes

Em ter., 30 de jun. de 2020 às 01:44, David Blevins 
escreveu:

> > On Jun 29, 2020, at 7:56 PM, Willes Reis  wrote:
> >
> > By the way, I did want only to respond to you as early, but we can talk
> > more soon.
>
> Hi Willes, looks like you grabbed TOMEE-55 and sounds like you might have
> been intending to reach out to David Jencks.
>
> If you do want to work on TOMEE-2346 let me know, otherwise I'll leave it
> unassigned.
>
>
> -David
>
>

Re: TOMEE-2341 - TomEE Site Generator

[David Blevins]

> On Jun 29, 2020, at 7:56 PM, Willes Reis  wrote:
> 
> By the way, I did want only to respond to you as early, but we can talk
> more soon.

Hi Willes, looks like you grabbed TOMEE-55 and sounds like you might have been 
intending to reach out to David Jencks.

If you do want to work on TOMEE-2346 let me know, otherwise I'll leave it 
unassigned.


-David



smime.p7s
Description: S/MIME cryptographic signature

Re: TOMEE-2341 - TomEE Site Generator

[Willes Reis]

Hi David Jencks,

It's a pleasure to help, although I have been a member for some time, I
have not been able to help much.
So much that I remember seeing you discussing the proposal about Antora,
that by the way, in my poor opinion, the proposal is very relevant.

But, we'll talk a lot about this yet.

Reading your considerations about the issue, I understand a little more the
proposal and agree with you. It does not look cool to force the writing of
javadoc using a specific format.

By the way, I did want only to respond to you as early, but we can talk
more soon.

See you!
Willes

Em dom., 28 de jun. de 2020 às 15:37, David Jencks 
escreveu:

> Hi Willes,
>
> It’s great to see someone interested in improving the state of the
> documentation!
>
> Earlier this year I spent a lot of time working on a proposal to move the
> TomEE documentation to an Antora based structure.  I didn’t get much
> response from the community and left it for a while, but am considering
> working on it some more.I think structurally the work is pretty much
> done but there are a bunch of, basically, presentation issues that could
> use improvement.  If this is adopted it’s likely to make many or most
> earlier doc issues somewhat obsolete.  The last prototype site I came up
> with is at
> https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/docs.html <
> https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/docs.html>.
> Having some help with this would be great.
>
> With regard to the issue you mention here, here are my thoughts:
>
> - I don’t understand why the custom code is used to assemble the unified
> javadoc jar.  I think the maven javadoc plugin can be configured to do it.
> - I thought the asciidoclet plugin was already configured, but it won’t do
> anything until someone writes some javadoc using asciidoc :-)
> - I’m not quite sure what David Blevins means by an index, but it might be
> trivial for the Antora built site.
> - 4 is done
> - Links from javadoc to actual class usage is a great idea, but how to do
> it is not so obvious.  I left a small comment on the sub-task.
>
> Anyway, Welcome!!
> David Jencks
>
> > On Jun 27, 2020, at 10:15 PM, Willes Reis  wrote:
> >
> > Hi David Blevins,
> >
> > Looking at the JIRA issue
> https://issues.apache.org/jira/browse/TOMEE-2341 on
> > which you are the reporter, I realized that there are 5 sub-tasks (2
> closed
> > / 3 open) and I would like to help with something in this, but I don't
> know
> > if the proposal is still valid? If ok, could you please explain the
> > expectations?
> >
> > Any feedback is appreciated.
> >
> > Best regards and stay healthy!
> > Willes Reis
>
>

Re: TOMEE-2341 - TomEE Site Generator

[David Blevins]

> On Jun 27, 2020, at 10:15 PM, Willes Reis  wrote:
> 
> Looking at the JIRA issue https://issues.apache.org/jira/browse/TOMEE-2341 on
> which you are the reporter, I realized that there are 5 sub-tasks (2 closed
> / 3 open) and I would like to help with something in this, but I don't know
> if the proposal is still valid? If ok, could you please explain the
> expectations?
> 
> Any feedback is appreciated.

Hi Willes!

Absolutely.  Any collaboration in this area is definitely welcome.  The most 
exciting of the tickets that I've really been dying to work on is 
https://issues.apache.org/jira/browse/TOMEE-2346 which is basically to 1) 
restore an old feature and 2) improve while we're at it.

When we used the Apache CMS we had an extension that would basically grep the 
source for the example and automatically append this list of links, see "APIs 
Used" at the bottom:

 - http://tomee.apache.org/examples-trunk/cdi-request-scope/README.html

The improvement part is since we are aggregating and publishing all the Jakarta 
EE and MicroProfile javadocs on the TomEE website, let's link to those Javadocs 
and while we're at it make them link back to the example.

Short history of the site generator is Romain wrote it in 2016.  I picked it up 
in Dec 2018 when he stopped working on it.  As I know from my own experience it 
takes a bit to digest, I've gone ahead and wrote the basic plumbing so we're 
right up close to the actual problem and you have a better chance at helping.  
Here's that diff:

 - 
https://github.com/apache/tomee-site-generator/commit/dec4194bc77ca5eb2a1dcf36bb43a51bc4b5cb84

I think the smallest step into the code for you would be to implement this 
class and get this test case to run:

 - 
https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/SeeLinks.java#L26
 - 
https://github.com/apache/tomee-site-generator/blob/master/src/test/java/org/apache/tomee/website/SeeLinksTest.java#L28

Once that is implemented, we should magically start seeing links show up in the 
correct Javadocs.

I suspect we'll go back and forth a few times hammering out issues.  Once that 
part is done we can move to the part of adding links in the example itself.

If we can nail those two things, we're done with TOMEE-2346 :)

Don't hesitate to ask questions on how to build/run the project.  There is 
slight documentation there, but it can always be better.  If you struggle for 
more than a half-hour or so, shoot off an email.  Definitely do not spend 
several hours stuck on something -- sure, you might be able to figure it out, 
but the next person will hit the same issue.


-David



smime.p7s
Description: S/MIME cryptographic signature

Re: TOMEE-2341 - TomEE Site Generator

[David Jencks]

Hi Willes,

It’s great to see someone interested in improving the state of the 
documentation!

Earlier this year I spent a lot of time working on a proposal to move the TomEE 
documentation to an Antora based structure.  I didn’t get much response from 
the community and left it for a while, but am considering working on it some 
more.I think structurally the work is pretty much done but there are a 
bunch of, basically, presentation issues that could use improvement.  If this 
is adopted it’s likely to make many or most earlier doc issues somewhat 
obsolete.  The last prototype site I came up with is at 
https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/docs.html 
.  Having 
some help with this would be great.

With regard to the issue you mention here, here are my thoughts:

- I don’t understand why the custom code is used to assemble the unified 
javadoc jar.  I think the maven javadoc plugin can be configured to do it.
- I thought the asciidoclet plugin was already configured, but it won’t do 
anything until someone writes some javadoc using asciidoc :-)
- I’m not quite sure what David Blevins means by an index, but it might be 
trivial for the Antora built site.
- 4 is done
- Links from javadoc to actual class usage is a great idea, but how to do it is 
not so obvious.  I left a small comment on the sub-task.

Anyway, Welcome!!
David Jencks

> On Jun 27, 2020, at 10:15 PM, Willes Reis  wrote:
> 
> Hi David Blevins,
> 
> Looking at the JIRA issue https://issues.apache.org/jira/browse/TOMEE-2341 on
> which you are the reporter, I realized that there are 5 sub-tasks (2 closed
> / 3 open) and I would like to help with something in this, but I don't know
> if the proposal is still valid? If ok, could you please explain the
> expectations?
> 
> Any feedback is appreciated.
> 
> Best regards and stay healthy!
> Willes Reis

TOMEE-2341 - TomEE Site Generator

[Willes Reis]

Hi David Blevins,

Looking at the JIRA issue https://issues.apache.org/jira/browse/TOMEE-2341 on
which you are the reporter, I realized that there are 5 sub-tasks (2 closed
/ 3 open) and I would like to help with something in this, but I don't know
if the proposal is still valid? If ok, could you please explain the
expectations?

Any feedback is appreciated.

Best regards and stay healthy!
Willes Reis