Sentry Maven Skin

The Sentry Maven Skin is an Apache Maven site skin to be used to generate Sentry's technical user documentation, using modern-era development tools (git, maven, markdown), and producing modern-era Web-based documentation (HTML5, Bootstrap, etc.)

To use the Sentry Maven Skin, read the full documentation.

Structure and technologies

Beware that this project is a baroc mix of languages, frameworks and libraries:

• Java for some backend HTML processing
• Javascript-in-Java with GraalVM for building the index
• Velocity for templating
• AngularJS for front-end logic
• Various HTML, CSS and JS frameworks and libraries (Bootstrap, etc.)
• npm and Gulp.js to build the front-end
• Groovy for validating the integration tests

The Sentry Maven Skin project is made of several main components:

• ./src/webapp/**: the front-end web app, including CSS, JS, HTML templates, etc.
• ./src/webapp/site.vm: the Velocity template that will generate each HTML page, this is the one referencing the JS and CSS
• ./src/package.json: for NPM
• ./src/gulpfile.js: to build and minify the web app
• ./src/it/studio-km: an integration test using a slightly customized version of Monitoring Studio's documentation

Build

The build is done with Maven with the below command:

mvn verify

Build steps:

• NodeJS is installed in ./node (and is ignored by Git)
• npm install is run to get all dependencies listed in package.json, which are installed in the ./node_modules (also ignored by Git)
• gulp is run with ./gulpfile.js to build the front-end web app (lint, minification, template embedding, etc.), and the result is stored in ./target/dist
• The Maven skin JAR is assembled in ./target
• A temporary local Maven repository is set up with both JAR artifacts (the skin and the Velocity tools)
• A test project is set up in ./target/it and mvn site is run on this test project
• The result validated with a Groovy script

Test

While modifying the Sentry Maven Skin, you will want to see how your changes are reflected in a test documentation project.

Conveniently, the project comes with integration tests, i.e. a documentation project that is automatically built with the skin as it is in the workspace. The integration test is run with the below command:

mvn verify

This command builds the skin and run it against a documentation project. The result can be seen in ./sentry-maven-skin/target/it/studio-km/site/*.html.

We recommend running http-server to browse the result. Install with:

npm install --global http-server

Launch a Web server with the generated test documentation with:

http-server sentry-maven-skin/target/it/studio-km/target/site

In case of a build failure, the output of the build is stored in ./sentry-maven-skin/target/it/studio-km/build.log.