You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomee.apache.org by Willes Reis <wi...@gmail.com> on 2020/06/28 05:15:32 UTC
TOMEE-2341 - TomEE Site Generator
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
Posted by David Blevins <da...@gmail.com>.
> On Jun 28, 2020, at 11:08 PM, David Blevins <da...@gmail.com> 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
Re: TOMEE-2341 - TomEE Site Generator
Posted by Willes Reis <wi...@gmail.com>.
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 <da...@gmail.com>
escreveu:
> > On Jun 27, 2020, at 10:15 PM, Willes Reis <wi...@gmail.com> 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
>
>
Re: TOMEE-2341 - TomEE Site Generator
Posted by David Blevins <da...@gmail.com>.
> On Jun 27, 2020, at 10:15 PM, Willes Reis <wi...@gmail.com> 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
Re: TOMEE-2341 - TomEE Site Generator
Posted by David Blevins <db...@tomitribe.com>.
> On Jun 30, 2020, at 10:48 AM, Willes Reis <wi...@gmail.com> 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
Posted by Willes Reis <wi...@gmail.com>.
> 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 <da...@gmail.com>
escreveu:
> > On Jun 29, 2020, at 7:56 PM, Willes Reis <wi...@gmail.com> 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
Posted by David Blevins <da...@gmail.com>.
> On Jun 29, 2020, at 7:56 PM, Willes Reis <wi...@gmail.com> 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
Posted by Willes Reis <wi...@gmail.com>.
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 <da...@gmail.com>
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 <wi...@gmail.com> 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
Posted by David Jencks <da...@gmail.com>.
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 <wi...@gmail.com> 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