Re: TOMEE-2341 - TomEE Site Generator

[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