What you need
Apache Forrest
Publishing framework used for Apache Gora Website maintenance.
How to modify the docs
The site docs at Gora are in two places, release independent docs are here 1, and per-release docs are at here 2.
Our reasoning behind this is that, the per-release docs contain the release-specific information (like Javadoc, tutorial, etc), we believe that this documentation is distributed in the tar ball, and everyone should be able to build and use the docs locally. Release independent docs contain the regular site information such as mailing lists, issue tracker, etc.
So, with that said, the release-independent docs are deployed at the root directory (http://gora.aapache.org), and every release doc should go under it's release number (like http://gora.apache.ord/docs/r0.1-incubating/), and finally, docs for trunk go under http://i.a.o/gora/docs/current/. Make any changes you see fit then from either of the two directories containing the forrest.properties file execute
| Code Block |
|---|
$ export FORREST_HOME=/path/to/forrest/directory $ export PATH=$PATH:$FORREST_HOME/bin $forrest |
This will build the site docs. Now we'll move on to reviewing the changes, then committing them.
Reviewing changes to the documentation and Gora site
From the same directory which you built the site from execute:
| Code Block |
|---|
$ forrest run |
This will start Forrest's built-in Jetty web server. Once it has started, point your browser at http://localhost:8888/, which will show your website, rendered on demand as each link is followed.
(Alternatively, if you wish to run Forrest from within an existing servlet container, type forrest webapp to build an open webapp in build/webapp/). You can now edit the XML content in build/webapp/content/xdocs and see the changes immediately in the browser.
After this, type:
| Code Block |
|---|
$ forrest validate |
to ensure that things are in order.
If you aren't a committer for Gora, you now need to get in touch with the development team, or alternatively open a Jira ticket and submit a patch.. You'll specifically want to learn how to create a patch and proposing your work. If you are a committer, it's time to deploy the site.
How to deploy the site
When you are finally happy with your changes in the case of the docs at 1, copy all of the files from the documentation author/build/site directory to /publish and commit both of them from the top of the /site directory directly to SVN.
In the case of the docs at 2, you need to copy them from the /build/site directory to the /publish directory in 1. You will then be able to commit from the top of the /site directory at 1 directly to SVN.
The modifications should be visible on the website within a few minutes.
1 https://svn.apache.org/repos/asf/gora/site/
2 https://svn.apache.org/repos/asf/gora/trunk/docs