Documentation Documentation

Doc Doc - Goose?

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

  1. Markdown - Some of this site is written in the Markdown format. Markdown source files are located in: src/site/markdown.

  2. You may also find a file at the project root.

Doc Publishing

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:

  1. Ensure a truly fresh copy of the site files.

     mvn clean
  2. 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.

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

For more details see: Maven Multi Module Configuration