TomEE Website Proposal

Add content

Documentation is in src/main/jbake/content, it follows the sitemap/structure. If you add a new page ensure to add a link to it please.

Preferred format is asciidoc.

Here a sample for a new page:

= My New Page
:jbake-date: 2017-03-16
:jbake-type: page
:jbake-status: published
:jbake-tomeepdf:

This page will rocks.

- One point
- Another point

=== Subtitle

Some content.

Tip	to run the website check the build section or run the main org.apache.tomee.website.JBake, it will log the local address to access the dev website and enable you to type r[ENTER] to rebuild it without restarting.

Build

To build the final website just use:

mvn compile

For development mvn compile -Djbake.http=true starts a server on http://localhost:8080 and auto refreshes pages after updates.

Then website is generated in target/site-${version} and you just need to sync it with CMS repo.

Note	it also opens the door to documentation versioning with subfolder per version like maven does.

Tip	the rendering is just a main so if the process doesn’t work for you just enrich it in JBake class.

Extensions

Build will generate a PDF for each page containing the attribute jbake-tomeepdf.

Examples

TomEE examples (${tomee.master}/examples) generates samples. It relies on Examples class which requests on github the README.md for each subfolder of examples folder.

For rate limit reason examples are cached locally in examples.cache and you can set your github auth header (Authorization) setting the system property -Dgithub.auth to have a higher rate limit.

The cache is just the github response excepted the content of the files which are decoded (base64).

Then the main calls org.apache.tomee.website.Examples.populateTree which creates the examples in src/main/jbake/content/examples. If you want to take into account another example you need to delete the cache before re-running the generation.

Finally note that the site generation will rely on the cache as well to generate the examples home page.

Publish (needs an ASF account)

SvnPub is a main to push to the staging the site content once built, you need to set the system properties (or properties in ~/.m2/settings.xml) site.password to your asf password and site.username if you user name is not USER environment variable for it to work.

It will checkout/update the site from svn then copy the site folder from target directory to synchronize it with the svn version and finally it will commit everything.

You can set the system property site.message to not use the default commit message.

Note	.content-site-checkout will be the local copy of the website (if you need to modify manually the files or delete some old ones.

Note	if the process fails unexpectedly (wrong update in the logic or anything) you can unlock the .content-site-checkout executing inside svn cleanup.

To build and deploy on staging at once: mvn clean compile pre-site.

Then to deploy to "prod": go on https://cms.apache.org/tomee/publish and hit "Submit" (note: you can review changes before if you want to check what the CMS took as changes).

Tip	the staging is available when https://ci.apache.org/builders/tomee-site-staging build is done (triggered on commit), you can’t deploy before.