Fugerit Document Generation Framework (fj-doc)

Fugerit Venus Doc Maven Plugin

back to fj-doc index

Description :
Ability to add fj-doc configuration to an existing project

Status :
All basic features are implemented.

Since : fj-doc 8.6.0

Available goals

goal	since	description
add	8.6.0	add Venus Doc Configuration to an existing project
verify	8.7.0	verify the templates in a FreeMarker configuration (folder), note: it can be used on any Apache FreeMarker configuration, not only Fugerit Venus Doc.
init	8.7.2	create a new project project already configured (actually an extension to ‘add’ goal); an UI is available on the playground too.

NOTE: Even though possible, it is not a recommended to run the ‘add’ or ‘init’ plugin with setting a ‘version’ parmeter lower than ‘8.7.4’ (see issue #180)

Goal : add

add Venus Doc Configuration to an existing project

Quickstart :

Default configuration :

mvn org.fugerit.java:fj-doc-maven-plugin:add

Custom configuration :

mvn org.fugerit.java:fj-doc-maven-plugin:add \
-Dextensions=base,freemarker,mod-fop

Add Fugerit Venus, parameters

parameter	required	default	description
version	true	latest stable	fj-doc version to add to the project (i.e. ‘8.7.5’), advice: keep the default unless a specific version is strictly needed.
extensions	true	base,freemarker	List of fj-doc core modules to add (*)
projectFolder	true	.	Maven project base folder
addDocFacade	true	true	If true, a stub doc configuration helper will be created
force	false	false	Will force project setup even if fj-doc already configured (warning: can overwrite configuration)
excludeXmlApis	false	false	It will exclude dependency xml-apis:xml-apis
addExclusions	false		Add comma separated exclusion, for instance : xml-apis:xml-apis,${groupId}:${artificatId}
addVerifyPlugin	true	true	If set to true, it will configure the ‘verify’ goal on the project
addJunit5	true	true	If set to true, it will add junit5 (test scope) and basic test
addLombok	true	true	If set to true, it will add lombok (provided scope) and slf4j-simple (test scope)
addDependencyOnTop	true	false	If set to true, added dependencies will be added before existing ones
freemarkerVersion	true	2.3.32	Freemarker compatibility version (max 2.3.33)

Add Fugerit Venus, available extensions

short name	full name	type handler	description
base	fj-doc-base	md	library base, xml as format for document template
freemarker	fj-doc-freemarker	html	Template and configuration functionalities based on Apache FreeMarker
mod-fop	fj-doc-mod-fop	fo, pdf	Type handler based on Apache FOP
mod-poi	fj-doc-mod-poi	xls, xlsx	Type handler based on Apache POI
mod-opencsv	fj-doc-mod-opencsv	opencsv	Type handler based on OpenCSV
mod-openpdf-ext	fj-doc-mod-openpdf-ext	pdf	Type handler based on OpenPDF
mod-openrtf-ext	fj-doc-mod-openrtf-ext	rtf	Type handler based on OpenRTF
base-json	fj-doc-base-json		add support to use json documents as format for document template
base-yaml	fj-doc-base-yaml		add support to use yaml documents as format for document template

Goal : init

Create a new project and add Venus Doc Configuration to it.

Quickstart :

mvn org.fugerit.java:fj-doc-maven-plugin:init \
-DgroupId=org.example.doc \
-DartifactId=fugerit-demo

Project folder will be ./${artifactId}/.

Init Fugerit Venus, parameters

parameter	required	default	description
groupId	true		new project group id
artifactId	true		new project artifact id
projectVersion	true	1.0.0-SNAPSHOT	new project version
javaRelease	true	21	java release version
flavour	true	vanilla	the flavour for the new project (see below for options)
flavourVersion	false	see below	override default framework version if supported (recommended : leave default or blank)

NOTE:

• it is possible to set any property from ‘add’ goal, except ‘projectFolder’ which is set to ./${artifactId}.

flavour	description	constraints	note	default flavourVersion
vanilla	basic Venus configuration		a vanilla maven project will be configured
quarkus-latest	project based on quarkus latest version	java >= 17	currently from the quarkus 3.X branch	as quarkus-3
quarkus-2	project based on quarkus 2	java == 11	2.16.12.Final is the latest version for quarkus 2.x	2.16.12.Final
quarkus-3	project based on quarkus 3	java >= 17	currently same as quarkus-latest	3.14.3
springboot-3	project based on springboot 3	java >= 17	based on SpringBoot 3.x	3.3.3
micronaut-4	project based on micronaut 4	java >= 17	based on Micronaut 4.x	4.6.2
openliberty	project based on openliberty	java >= 17	based on OpenLiberty	20.0.0.9

Goal : verify

verify the templates in a FreeMarker configuration (folder), note: it can be used on any Apache FreeMarker configuration, not only Fugerit Venus Doc.

Quickstart :

Verify existing FreeMarker configuration

mvn org.fugerit.java:fj-doc-maven-plugin:verify -DtemplateBasePath=./src/test/resources/fj_doc_test/template-fail

Verify FreeMarker configuration at maven build time

  <plugin>
    <groupId>org.fugerit.java</groupId>
    <artifactId>fj-doc-maven-plugin</artifactId>
    <version>${fj-doc-version}</version>
    <executions>
      <execution>
        <id>freemarker-verify</id>
        <phase>compile</phase>
        <goals>
          <goal>verify</goal>
        </goals>
      </execution>
    </executions>
    <configuration>
      <!-- Where the FreeMarker templates are located -->
      <templateBasePath>${project.basedir}/src/main/resources/fugerit-blank/template</templateBasePath>
      <!-- WARNING: if set to 'true', build will fail when at least one syntax error is found -->
      <failOnErrors>true</failOnErrors>
      <!-- If 'true' a report will be generated (when 'true', param reportOutputFolder is required) -->
      <generateReport>true</generateReport>
      <!-- Template syntax verify report output folder -->
      <reportOutputFolder>${project.build.directory}/freemarker-syntax-verify-report</reportOutputFolder>
    </configuration>
  </plugin>

Verify FreeMarker parameters

parameter	required	default	description
templateBasePath	true		Path to base folder containing FreeMarker templates
freemarkerVersion	false	latest stable	FreeMarker configuration ( i.e. 2.3.33)
templateFilePattern	false		Filter on templates to be checked, regex on filename, i.e. “.{0,}[.]ftl”
failOnErrors	true	true	If set to true the build will fail when template syntax errors will be found, otherwise errors will be only logged
generateReport	false	false	If set to true a report will be generated (and property ‘reportOutputFolder’ will be olso required).
reportOutputFolder	false		Output folder for the generated report.
reportOutputFormat	false	‘html’	Output format for the generated report, supported : html (default), pdf, csv, xlsx, md.