| = 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`. | |
| **Note**: Currently, the PDF generation is disabled. | |
| == 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) | |
| - The website is automatically build and published to https://github.com/apache/tomee-site-pub[TomEE Site Pub] by a https://ci-builds.apache.org/job/Tomee/job/site-publish/[Jenkins build job] every 12 hours. | |
| - The job can also be triggered manually via the Jenkins website. |