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