Skip to content

sentrysoftware/sentry-maven-skin

Repository files navigation

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

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.