Added fj-doc-maven-plugin

fugerit-org · Aug 21, 2024 · afcf3bf · afcf3bf
1 parent f0e6283
commit afcf3bf
Show file tree

Hide file tree

Showing 19 changed files with 952 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- fj-doc-maven-plugin (configure a maven project for Fugerit Venus Doc usage)
+
 ## [8.5.2] - 2024-08-14
 
 ### Changed

diff --git a/README.md b/README.md
@@ -82,6 +82,7 @@ A quick start is available in module [fj-doc-sample](fj-doc-sample/README.md)
 There are five kinds of components (each components README.md contains module status) : 
 
 ### 1. Framework core :
+
 * [Core library (fj-doc-base)](fj-doc-base/README.md) (contains a simple renderer for [Markdown BASIC](fj-doc-base/src/main/java/org/fugerit/java/doc/base/typehandler/markdown/SimpleMarkdownBasicTypeHandler.java) and [Markdown EXT](fj-doc-base/src/main/java/org/fugerit/java/doc/base/typehandler/markdown/SimpleMarkdownExtTypeHandler.java))
 * [Json extension (fj-doc-base-json)](fj-doc-base-json/README.md) (allow for using json as document generator instead of standard xml generator) [since 0.7.0]
 * [Yaml extension (fj-doc-base-yaml)](fj-doc-base-yaml/README.md) (allow for using yaml as document generator instead of standard xml generator) [since 0.7.0]
@@ -134,10 +135,23 @@ You can find in them in a dedicated repository [fj-doc-ext](https://gitlab.com/f
 * [Java EE extension (fj-doc-ent)](https://github.com/fugerit-org/fj-doc-ent.git) (deprecated as not the module fj-mod-freemarker provided mostly the same features, but in a standalone mode) (deprecated since version 0.5.0)
 
 ### 9. GraalVM native support  
+
 Beginning with version 1.4.0-rc.001, *GraalVM* metadata started to be added (*reflect-config.json* and *resources-config.json*). Initially only the *fj-doc-base* and *fj-doc-freemarker* have full support.
 Actual support for other module will be added as soon as possible, but sometimes is dependent on underlying dependencies support (for example *Apache FOP* for *fj-doc-mod-fop*).
 It is possible to check the current status on the module documentation, in the section *native support*
 
+### 10. Maven Plugin
+
+A [maven plugin](fj-doc-maven-plugin/README.md) is also available. It allows to configure a maven project for document generation, it is as simple as : 
+
+```shell
+mvn org.fugerit.java:fj-doc-maven-plugin:add \
+-Dextensions=base,freemarker,mod-fop \
+-Dversion=8.5.3
+```
+
+See [Documentation](fj-doc-maven-plugin/README.md) for further details.
+
 *About javadoc*  
 Javadoc are far from being complete, but you can find latest version at [https://www.fugerit.org](https://www.fugerit.org/data/java/javadoc/)  
 Note that, being an open source project hosted on maven central, you can find release javadoc on [javadoc.io](https://javadoc.io/doc/org.fugerit.java/fj-doc-base/)

diff --git a/fj-doc-freemarker/src/test/resources/fj_doc_test/freemarker-doc-process.xml b/fj-doc-freemarker/src/test/resources/fj_doc_test/freemarker-doc-process.xml
@@ -4,6 +4,8 @@
 	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="https://freemarkerdocprocess.fugerit.org https://www.fugerit.org/data/java/doc/xsd/freemarker-doc-process-1-0.xsd" > 	
 
+
+
 	<docChain id="shared">
 		<chainStep stepType="config">
 			<config id="FJ_DOC_TEST"

diff --git a/fj-doc-maven-plugin/README.md b/fj-doc-maven-plugin/README.md
@@ -0,0 +1,52 @@
+# Fugerit Document Generation Framework (fj-doc)
+
+## Fugerit Venus Doc Maven Plugin
+
+[back to fj-doc index](../README.md)
+
+*Description* :  
+Ability to add fj-doc configuration to an existing project
+
+*Status* :  
+All basic features are implemented.  
+
+*Since* : fj-doc 8.5.3
+
+*Quickstart* :
+
+Default configuration : 
+
+```shell
+mvn org.fugerit.java:fj-doc-maven-plugin:add
+```
+
+Custom configuration :
+
+```shell
+mvn org.fugerit.java:fj-doc-maven-plugin:add \
+-Dextensions=base,freemarker,mod-fop \
+-Dversion=8.5.3
+```
+
+*Parameters*
+
+| parameter     | required | default         | description                                              |
+|---------------|----------|-----------------|----------------------------------------------------------|
+| version       | true     | latest stable   | fj-doc version to add to the project (i.e. '8.5.3')      |
+| 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 |
+
+*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](https://freemarker.apache.org/) |
+| mod-fop         | fj-doc-mod-fop         | fo, pdf      | Type handler based on [Apache FOP](https://xmlgraphics.apache.org/fop/)                                 |
+| mod-poi         | fj-doc-mod-poi         | xls, xlsx    | Type handler based on [Apache POI](https://poi.apache.org/)                                             |
+| mod-opencsv     | fj-doc-mod-opencsv     | opencsv      | Type handler based on [OpenCSV](https://opencsv.sourceforge.net/)                                       |
+| mod-openpdf-ext | fj-doc-mod-openpdf-ext | pdf          | Type handler based on [OpenPDF](https://github.com/LibrePDF/OpenPDF)                                    |
+| mod-openrtf-ext | fj-doc-mod-openrtf-ext | rtf          | Type handler based on [OpenRTF](https://github.com/LibrePDF/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                                       |
diff --git a/fj-doc-maven-plugin/pom.xml b/fj-doc-maven-plugin/pom.xml
@@ -0,0 +1,112 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<artifactId>fj-doc-maven-plugin</artifactId>
+
+	<parent>
+		<groupId>org.fugerit.java</groupId>
+		<artifactId>fj-doc</artifactId>
+		<version>8.5.3-SNAPSHOT</version>
+	</parent>
+
+	<packaging>maven-plugin</packaging>
+
+	<name>fj-doc-maven-plugin</name>
+
+	<description>Maven plugin to add Fugerit Venus Doc to a mavne project (fj-doc:generate)</description>
+
+	<properties>
+		<mvn-site-plugin-version>3.12.1</mvn-site-plugin-version>
+		<mvn-project-info-reports-plugin>3.6.0</mvn-project-info-reports-plugin>
+		<!-- 'report' goal seems not to work with lastest version, 3.9.0 --> 
+		<mvn-plugin-version>3.13.1</mvn-plugin-version>
+	</properties>
+
+	<licenses>
+		<license>
+			<name>Apache License, Version 2.0</name>
+			<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+			<distribution>repo</distribution>
+		</license>
+	</licenses>
+
+	<build>
+
+	    <pluginManagement>
+	        <plugins>
+	            <plugin>
+	                <groupId>org.apache.maven.plugins</groupId>
+	                <artifactId>maven-plugin-plugin</artifactId>
+	                <version>${mvn-plugin-version}</version>
+	            </plugin>
+	            <plugin>
+	                <groupId>org.apache.maven.plugins</groupId>
+	                <artifactId>maven-site-plugin</artifactId>
+	                <version>${mvn-site-plugin-version}</version>
+	            </plugin>
+	            <plugin>
+				    <groupId>org.apache.maven.plugins</groupId>
+				    <artifactId>maven-project-info-reports-plugin</artifactId>
+				    <version>${mvn-project-info-reports-plugin}</version>					
+				</plugin>           
+	        </plugins>
+	    </pluginManagement>
+
+	</build>
+
+	<dependencies>
+
+		<dependency>
+			<groupId>org.apache.maven</groupId>
+			<artifactId>maven-plugin-api</artifactId>
+			<scope>provided</scope>
+		</dependency>
+
+		<dependency>
+			<groupId>org.apache.maven.plugin-tools</groupId>
+			<artifactId>maven-plugin-annotations</artifactId>
+		</dependency>
+
+		<dependency>
+			<groupId>org.fugerit.java</groupId>
+			<artifactId>fj-core</artifactId>
+		</dependency>
+
+		<dependency>
+			<groupId>org.fugerit.java</groupId>
+			<artifactId>fj-doc-freemarker</artifactId>
+		</dependency>
+
+		<dependency>
+			<groupId>org.maxxq.maven</groupId>
+			<artifactId>maxxq-maven</artifactId>
+			<version>1.3.0</version>
+		</dependency>
+
+	</dependencies>
+
+	<organization>
+		<url>https://www.fugerit.org</url>
+		<name>Fugerit</name>
+	</organization>
+
+	<url>https://www.fugerit.org/perm/venus</url>
+
+	<reporting>
+	    <plugins>
+	        <plugin>
+	            <groupId>org.apache.maven.plugins</groupId>
+	            <artifactId>maven-plugin-plugin</artifactId>
+	            <reportSets>
+	                <reportSet>
+	                    <reports>
+	                        <report>report</report>
+	                    </reports>
+	                </reportSet>
+	            </reportSets>
+	        </plugin>
+	    </plugins>
+	</reporting>	
+
+</project>
diff --git a/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/maven/MojoAdd.java b/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/maven/MojoAdd.java
@@ -0,0 +1,36 @@
+package org.fugerit.java.doc.maven;
+
+import org.apache.maven.plugin.AbstractMojo;
+import org.apache.maven.plugin.MojoExecutionException;
+import org.apache.maven.plugin.MojoFailureException;
+import org.apache.maven.plugins.annotations.Mojo;
+import org.apache.maven.plugins.annotations.Parameter;
+import org.fugerit.java.doc.project.facade.AddVenusFacade;
+import org.fugerit.java.doc.project.facade.VenusContext;
+
+import java.io.File;
+
+@Mojo( name = "add" )
+public class MojoAdd extends AbstractMojo {
+
+    @Parameter(property = "version", defaultValue = "8.5.2", required = true)
+    protected String version;
+
+    @Parameter(property = "extensions", defaultValue = "base,freemarker", required = true)
+    protected String extensions;
+
+    @Parameter(property = "projectFolder", defaultValue = ".", required = true)
+    protected String projectFolder;
+
+    @Parameter(property = "addDocFacade", defaultValue = "true", required = true)
+    protected boolean addDocFacade;
+
+    @Override
+    public void execute() throws MojoExecutionException, MojoFailureException {
+        VenusContext context = new VenusContext( new File( this.projectFolder ), this.version ,this.extensions );
+        context.setAddDocFacace( this.addDocFacade );
+        this.getLog().info( String.format( "add execute() context : %s", context ) );
+        AddVenusFacade.addVenusToMavenProject( context );
+    }
+
+}
diff --git a/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/AddVenusFacade.java b/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/AddVenusFacade.java
@@ -0,0 +1,132 @@
+package org.fugerit.java.doc.project.facade;
+
+import freemarker.cache.ClassTemplateLoader;
+import freemarker.cache.StringTemplateLoader;
+import freemarker.template.*;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.maven.model.Dependency;
+import org.apache.maven.model.DependencyManagement;
+import org.apache.maven.model.Model;
+import org.fugerit.java.core.cfg.ConfigException;
+import org.fugerit.java.core.function.SafeFunction;
+import org.fugerit.java.core.io.FileIO;
+import org.fugerit.java.core.io.StreamIO;
+import org.fugerit.java.core.javagen.JavaGenerator;
+import org.fugerit.java.core.javagen.SimpleJavaGenerator;
+import org.fugerit.java.core.lang.helpers.ClassHelper;
+import org.fugerit.java.doc.freemarker.config.FreeMarkerConfigStep;
+import org.fugerit.java.doc.freemarker.fun.SimpleMessageFun;
+import org.fugerit.java.doc.freemarker.process.FreemarkerDocProcessConfig;
+import org.fugerit.java.doc.freemarker.process.FreemarkerDocProcessConfigFacade;
+import org.maxxq.maven.dependency.ModelIO;
+
+import java.io.*;
+import java.nio.charset.StandardCharsets;
+import java.util.*;
+import java.util.stream.Collectors;
+
+@Slf4j
+public class AddVenusFacade extends BasicVenusFacade {
+
+    private AddVenusFacade() {}
+
+    private static final String EXAMPLE_FOLDER = "config/example/";
+
+    private static void addDocFacade( VenusContext context ) throws IOException, TemplateException, ConfigException {
+        // freemarker configuration
+        Configuration configuration = new Configuration( new Version( FreeMarkerConfigStep.ATT_FREEMARKER_CONFIG_KEY_VERSION_LATEST ) );
+        configuration.clearTemplateCache();
+        ClassTemplateLoader loader = new ClassTemplateLoader( AddVenusFacade.class, "/config/template/" );
+        configuration.setTemplateExceptionHandler( TemplateExceptionHandler.RETHROW_HANDLER );
+        configuration.setTemplateLoader( loader );
+        configuration.setDefaultEncoding(StandardCharsets.UTF_8.name());
+        // config generation
+        Template fmConfigTemplate = configuration.getTemplate( "fm-doc-process-config-template.ftl" );
+        Map<Object, Object> data = new HashMap<>();
+        data.put( "context" , context );
+        File fmConfigFile = new File( context.getProjectDir(), "src/main/resources/"+context.getResourcePathFmConfigXml() );
+        log.info( "fmConfigFile : {}, mk parent? : {}", fmConfigFile.getCanonicalPath(), fmConfigFile.getParentFile().mkdirs() );
+        File templateDir = new File( fmConfigFile.getParentFile(), context.getTemplateSubPath() );
+        log.info( "templateDir : {}, mk parent? : {}", templateDir.getCanonicalPath(), templateDir.mkdirs() );
+        try ( Writer writer = new FileWriter( fmConfigFile ) ) {
+            fmConfigTemplate.process( data, writer );
+        }
+        configuration.clearTemplateCache();
+        // copy sample template
+        String fileName = "document.ftl";
+        File documentExample = new File( templateDir, fileName );
+        try ( InputStream documentExampleIS = ClassHelper.loadFromDefaultClassLoader( EXAMPLE_FOLDER+fileName ) ) {
+            String documentContent = StreamIO.readString( documentExampleIS );
+            FileIO.writeString( documentContent, documentExample );
+        }
+        // create doc config
+        File sourceFolder = new File( context.getProjectDir(), "src/main/java" );
+        log.info( "sourceFolder : {}, mk parent? : {}", sourceFolder.getCanonicalPath(), sourceFolder.mkdirs() );
+        File resourceFolder = new File( context.getProjectDir(), "src/main/resources" );
+        log.info( "resourceFolder : {}, mk parent? : {}", resourceFolder.getCanonicalPath(), resourceFolder.mkdirs() );
+        DocConfigGenerator javaGenerator = new DocConfigGenerator( context );
+        Properties generatorProps = new Properties();
+        javaGenerator.init( sourceFolder, context.getDocConfigPackage()+"."+context.getDocConfigClass(), SimpleJavaGenerator.STYLE_CLASS, generatorProps);
+        javaGenerator.generate();
+        javaGenerator.write();
+        // create examples
+        String docExampleFileName = "DocHelperExample.java";
+        try ( InputStream documentExampleIS = ClassHelper.loadFromDefaultClassLoader( EXAMPLE_FOLDER+docExampleFileName ) ) {
+            String documentContent = StreamIO.readString( documentExampleIS ).replace( "[PACKAGE]", context.getDocConfigPackage() );
+            File docExampleFile = new File( new File( sourceFolder, context.getDocConfigPackage().replace( '.', '/' ) ), docExampleFileName );
+            FileIO.writeString( documentContent, docExampleFile );
+        }
+        if ( context.getModules().contains( "fj-doc-mod-fop" ) ) {
+            String fopConfigName = "fop-config.xml";
+            File fopConfig = new File( new File( resourceFolder, context.getArtificatIdForFolder() ),  fopConfigName );
+            try ( InputStream fopConfigExampleIS = ClassHelper.loadFromDefaultClassLoader( EXAMPLE_FOLDER+fopConfigName ) ) {
+                String fopConfigContent = StreamIO.readString( fopConfigExampleIS );
+                FileIO.writeString( fopConfigContent, fopConfig );
+            }
+        }
+    }
+
+    public static boolean addVenusToMavenProject( VenusContext context ) {
+        return SafeFunction.get( () -> {
+            File pomFile = new File( context.getProjectDir(), "pom.xml" );
+            log.info( "project dir : {}", context.getProjectDir().getCanonicalPath() );
+            if ( pomFile.exists() ) {
+                addExtensionList( pomFile, context );
+                if ( context.isAddDocFacace() ) {
+                    addDocFacade( context );
+                }
+            } else {
+                addErrorAndLog( String.format( "No pom file in project dir : %s", pomFile.getCanonicalPath() ), context );
+                return false;
+            }
+            return true;
+        } );
+    }
+
+}
+
+class DocConfigGenerator extends SimpleJavaGenerator {
+
+    private VenusContext context;
+
+    public DocConfigGenerator(VenusContext context) {
+        this.context = context;
+    }
+
+    @Override
+    public void init(File sourceFolder, String fullObjectBName, String javaStyle, Properties config) throws ConfigException {
+        super.init(sourceFolder, fullObjectBName, javaStyle, config);
+        this.setNoCustomComment( true );
+        this.getImportList().add( FreemarkerDocProcessConfig.class.getName() );
+        this.getImportList().add( FreemarkerDocProcessConfigFacade.class.getName() );
+    }
+
+    @Override
+    public void generateBody() throws IOException {
+        this.println( "     private FreemarkerDocProcessConfig docProcessConfig = FreemarkerDocProcessConfigFacade.loadConfigSafe( \"cl://"+this.context.getResourcePathFmConfigXml()+"\" );" );
+        this.println();
+        this.println( "     public FreemarkerDocProcessConfig getDocProcessConfig() { return this.docProcessConfig; }" );
+        this.println();
+    }
+
+}