build-mvn-site

This task can be used to build Maven sites. Beside calling Apache Maven, it also provides functionality to run scripts before building and before staging a site. Those scripts can take full advantage of the framework and its API. This allows to build even very complex sites in an automated way, with features realized outside the Maven build process but fully integrated into the overall site building.

The task is not specific to one site, but can build one or more sites, even within one execution. The parameter MVN_SITES is used to identify the sites that can be build. It should contain a set of paths to the site directories. Each of these directories should contain a pom file (pom.xml) with the Maven specifications for the site. It also should contain a framework-specific metadata file (skb-site.id). It might contain a file skb-site-scripts.skb with scripts to be run before the site build and before the site staging.

The general options, shown below, allow to direct the behavior of the task.

  • build - request one or more sites to be built

  • clean - requests to clean one or more sites. Clean will call mvn clean to do the job

  • list - will list all defined and loaded sites, which then can be build or cleaned.

  • test - once a site is successfully build, it can be tested. Testing here means to start a web browser with the site’s index.html file.

-b | --build            builds site(s), requires a target and site ID or all
-c | --clean            cleans all site(s)
-h | --help             print help screen and exit
-l | --list             list sites
-T | --test             test sites, open in browser

Target Options

The task can build a Maven site for several targets:

  • targets - builds all targets

  • ad - calls Maven with the argument site:attach-descriptor. This argument is important for multi-module sites with inherited descriptors

  • site - calls Maven to build the site, but not stage it

  • stage - calls Maven to stage a site that has been prior built successfully

-t | --targets          mvn: all targets
     --ad               mvn: site:attach-descriptor
     --site             mvn: site
     --stage            mvn: site:stage

There is no default target.

Filter Options

Filters allow to specify which of the loaded (and available) sites should be built:

  • all - will build all sites, in the oder they are listed (alphabetically)

  • id - can be used to build a specific site

-A | --all              all sites
-i | --id ID            site identifier for building

There is no default filter.

Maven Options

Further options exist to configure the runtime behavior of Maven:

  • profile - call Maven with a specific profile setting, e.g. when the site definitions in the POM file are within a profile

--profile PROFILE  mvn: use profile PROFILE

Examples

The framework’s own site can be build using this task. When correctly configured, the site can be listed

build-mvn-site --list

This will show (with a real path instead of SOME_PATH)

  Sites
   fw - SKB Framework site - SOME_PATH/dev/skb/bash/framework

The site can then be build using

build-mvn-site --build --id fw

The task and Maven output will be similar to:

[INFO] Scanning for projects...
[WARNING] The project de.vandermeer:skb-framework:pom:0.0.1 uses prerequisites which is only intended for maven-plugin projects but not for non maven-plugin projects. For such purposes you should use the maven-enforcer-plugin. See https://maven.apache.org/enforcer/enforcer-rules/requireMavenVersion.html
[INFO]
[INFO] --------------------< de.vandermeer:skb-framework >---------------------
[INFO] Building skb-framework 0.0.1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 0.079 s
[INFO] Finished at: 2018-11-15T21:08:19Z
[INFO] ------------------------------------------------------------------------
      -> building user guide (html, pdf)
      -> building task guide (html, pdf)
      -> building developer guide (html, pdf)
      -> building implementation doc (html, pdf)

Setting the task level to info will provide more information on the task’s progress.

Site Files

As mentioned above, a site suitable for this task should provide a file with its metadata and might provide a file with scripts to be used in the build. Both files must be located in the same directory as the POM file.

The metadata file must be named skb-site.id. It must contain the following information:

  • An identifier. This identifier can be any string that does not contain whitespaces or bash special characters (such as & or *). The identifier must be unique for all site in MVN_SITES.

  • A description. The description should be short, like a tag line, to fit into the listing of sites.

The source block below shows the file for the frameworks' site.


  
1
2


  
ID=fw
DESCRIPTION="the SKB Framework site"

The file skb-site-scripts.skb could be provided. If it does not exist, the task will build the site purely using Maven. If it does exist, the task will source the file and call two functions the file must provide. This means that the file can

  • Use anything a normal bash script can do at any place in the file

  • Use anything a normal bash script can do inside the two required functions

  • Use the full framework settings and API at any place in the file

The following code block shows the standard contents of the script file with the two required functions:

MvnSitePreScript() {
    # any code run before Maven is called to build the site
}

MvnSitePostScript() {
    # any code run `mvn site` but before `mvn site:stage`
}

To see an example have a look at the framework’s script file. The current file can be found in the Github repository: skb-site-scripts.skb. Here, the function MvnSitePreScript executes framework tasks to create files for the site. The function MvnSitePostScript calls tools from the AsciiDoctor tool chain to create documents. It also uses the framework’s API function MvnSiteFixAdoc, which helps to fix some AsciiDoctor problem in generated HTML files in the site.

Requirements

The task takes the sites it should load and build from the parameter MVN_SITES. If no sites are provided, or no sites could be loaded (due to a missing side identifier file), the task will throw an error.

Building a Maven site of course requires Maven (dependency maven), which in turn requires a JDK to be installed on the host as well.

Testing a site is done by starting a web browser with the site’s index.html file. This requires the task start-browser to be loaded and well-configured. Without this task be available, sites cannot be tested.