= 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:

[source,adoc]
----
= 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:

[source]
----
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)

- To publish the website, you have to add and push the related content to the https://github.com/apache/tomee-site-pub[TomEE Site Pub] repository.

== Legacy SVN Publish (not working anymore)

`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.