Documentation Documentation

Doc Doc - Goose?

Here is some documentation about how this documentation is written. Feel free to pitch-in and improve things.

Markdown - Some of this site is written in the Markdown format. Markdown source files are located in: src/site/markdown.
You may also find a README.md file at the project root.

To deploy these docs to gh-pages, we use maven-scm-publish-plugin.

Due to issues publishing a large multi-module site (MSCMPUB-18), we need to run a number of commands in order to successfully publish the site:

Ensure a truly fresh copy of the site files.
```
 mvn clean
```
Generate the entire site (including all sub-modules) in the target/staging folder.
```
 mvn clean package site site:stage
```
After running this command you can review a local copy of the site by opening: target/staging/index.html.
Publish the new site to github gh-pages branch.
```
 mvn scm-publish:publish-scm
```
Shorter commands (like mvn clean site-deploy) run into a number of problems. If you find a shorter incantation that works reliably, please share your findings!

NOTE: The first time publishing a large site tree, I saw some errors related to command size limits. The workaround for the first time publishing was to manually push large tree changes to the gh-pages branch. Thereafter the command size limit issue was avoided because fewer new changes were being published to gh-pages via the above publish command.