fixes based on romain's suggestion and adding video
[tomee-site-generator.git] / README.adoc
1 = TomEE Website Proposal
2
3 == Add content
4
5 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.
6
7 Preferred format is `asciidoc`.
8
9 Here a sample for a new page:
10
11 [source,adoc]
12 ----
13 = My New Page
14 :jbake-date: 2017-03-16
15 :jbake-type: page
16 :jbake-status: published
17 :jbake-tomeepdf:
18
19 This page will rocks.
20
21 - One point
22 - Another point
23
24 === Subtitle
25
26 Some content.
27 ----
28
29 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
30 enable you to type `r[ENTER]` to rebuild it without restarting.
31
32 == Build
33
34 To build the final website just use:
35
36 [source]
37 ----
38 mvn compile
39 ----
40
41 For development `mvn compile -Djbake.http=true` starts a server on http://localhost:8080 and auto refreshes
42 pages after updates.
43
44
45 Then website is generated in `target/site-${version}` and you just need to sync it with CMS repo.
46
47 NOTE: it also opens the door to documentation versioning with subfolder per version like maven does.
48
49 TIP: the rendering is just a main so if the process doesn't work for you just enrich it in `JBake` class.
50
51 == Extensions
52
53 Build will generate a PDF for each page containing the attribute `jbake-tomeepdf`.
54
55 == Examples
56
57 TomEE examples (${tomee.master}/examples) generates samples. It relies on `Examples` class
58 which requests on github the README.md for each subfolder of `examples` folder.
59
60 For rate limit reason examples are cached locally in examples.cache and you can set your
61 github auth header (`Authorization`) setting the system property `-Dgithub.auth` to have
62 a higher rate limit.
63
64 The cache is just the github response excepted the content of the files which are decoded (base64).
65
66 Then the main calls org.apache.tomee.website.Examples.populateTree which creates the examples
67 in `src/main/jbake/content/examples`. If you want to take into account another example you
68 need to delete the cache before re-running the generation.
69
70 Finally note that the site generation will rely on the cache as well to generate the examples home page.
71
72 == Publish (needs an ASF account)
73
74 `SvnPub` is a main to push to the staging the site content once built, you need to set the system properties (`MAVEN_OPTS`) `site.password`
75 to your asf password and `site.username` if you user name is not `USER` environment variable for it to work.
76
77 It will checkout/update the site from svn then copy the site folder from target directory to synchronize it with the svn version
78 and finally it will commit everything.
79
80 You can set the system property `site.message` to not use the default commit message.
81