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

Building This Project's Own Documentation

This project uses itself as its own Maven skin (dogfooding). Because of this, you must run mvn install before mvn site to ensure the skin JAR is available in your local Maven repository:

mvn install site

Running mvn site alone will fail because the skin artifact won't be found.

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.