Re: TOMEE-2341 - TomEE Site Generator

[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
>
>