Skip to content

Commit afcf3bf

Browse files
fugerit79fugerit79
committed
Added fj-doc-maven-plugin
1 parent f0e6283 commit afcf3bf

File tree

19 files changed

+952
-0
lines changed

19 files changed

+952
-0
lines changed

‎CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
### Added
11+
12+
- fj-doc-maven-plugin (configure a maven project for Fugerit Venus Doc usage)
13+
1014
## [8.5.2] - 2024-08-14
1115

1216
### Changed

‎README.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,7 @@ A quick start is available in module [fj-doc-sample](fj-doc-sample/README.md)
8282
There are five kinds of components (each components README.md contains module status) :
8383

8484
### 1. Framework core :
85+
8586
* [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))
8687
* [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]
8788
* [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
134135
* [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)
135136

136137
### 9. GraalVM native support
138+
137139
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.
138140
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*).
139141
It is possible to check the current status on the module documentation, in the section *native support*
140142

143+
### 10. Maven Plugin
144+
145+
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 :
146+
147+
```shell
148+
mvn org.fugerit.java:fj-doc-maven-plugin:add \
149+
-Dextensions=base,freemarker,mod-fop \
150+
-Dversion=8.5.3
151+
```
152+
153+
See [Documentation](fj-doc-maven-plugin/README.md) for further details.
154+
141155
*About javadoc*
142156
Javadoc are far from being complete, but you can find latest version at [https://www.fugerit.org](https://www.fugerit.org/data/java/javadoc/)
143157
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/)

‎fj-doc-freemarker/src/test/resources/fj_doc_test/freemarker-doc-process.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
55
xsi:schemaLocation="https://freemarkerdocprocess.fugerit.org https://www.fugerit.org/data/java/doc/xsd/freemarker-doc-process-1-0.xsd" >
66

7+
8+
79
<docChain id="shared">
810
<chainStep stepType="config">
911
<config id="FJ_DOC_TEST"

‎fj-doc-maven-plugin/README.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Fugerit Document Generation Framework (fj-doc)
2+
3+
## Fugerit Venus Doc Maven Plugin
4+
5+
[back to fj-doc index](../README.md)
6+
7+
*Description* :
8+
Ability to add fj-doc configuration to an existing project
9+
10+
*Status* :
11+
All basic features are implemented.
12+
13+
*Since* : fj-doc 8.5.3
14+
15+
*Quickstart* :
16+
17+
Default configuration :
18+
19+
```shell
20+
mvn org.fugerit.java:fj-doc-maven-plugin:add
21+
```
22+
23+
Custom configuration :
24+
25+
```shell
26+
mvn org.fugerit.java:fj-doc-maven-plugin:add \
27+
-Dextensions=base,freemarker,mod-fop \
28+
-Dversion=8.5.3
29+
```
30+
31+
*Parameters*
32+
33+
| parameter | required | default | description |
34+
|---------------|----------|-----------------|----------------------------------------------------------|
35+
| version | true | latest stable | fj-doc version to add to the project (i.e. '8.5.3') |
36+
| extensions | true | base,freemarker | List of fj-doc core modules to add (*) |
37+
| projectFolder | true | . | Maven project base folder |
38+
| addDocFacade | true | true | If true, a stub doc configuration helper will be created |
39+
40+
*Available extensions*
41+
42+
| short name | full name | type handler | description |
43+
|-----------------|------------------------|--------------|---------------------------------------------------------------------------------------------------------|
44+
| base | fj-doc-base | md | library base, xml as format for document template |
45+
| freemarker | fj-doc-freemarker | html | Template and configuration functionalities based on [Apache FreeMarker](https://freemarker.apache.org/) |
46+
| mod-fop | fj-doc-mod-fop | fo, pdf | Type handler based on [Apache FOP](https://xmlgraphics.apache.org/fop/) |
47+
| mod-poi | fj-doc-mod-poi | xls, xlsx | Type handler based on [Apache POI](https://poi.apache.org/) |
48+
| mod-opencsv | fj-doc-mod-opencsv | opencsv | Type handler based on [OpenCSV](https://opencsv.sourceforge.net/) |
49+
| mod-openpdf-ext | fj-doc-mod-openpdf-ext | pdf | Type handler based on [OpenPDF](https://github.com/LibrePDF/OpenPDF) |
50+
| mod-openrtf-ext | fj-doc-mod-openrtf-ext | rtf | Type handler based on [OpenRTF](https://github.com/LibrePDF/OpenRTF) |
51+
| base-json | fj-doc-base-json | | add support to use json documents as format for document template |
52+
| base-yaml | fj-doc-base-yaml | | add support to use yaml documents as format for document template |

‎fj-doc-maven-plugin/pom.xml

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
3+
<modelVersion>4.0.0</modelVersion>
4+
5+
<artifactId>fj-doc-maven-plugin</artifactId>
6+
7+
<parent>
8+
<groupId>org.fugerit.java</groupId>
9+
<artifactId>fj-doc</artifactId>
10+
<version>8.5.3-SNAPSHOT</version>
11+
</parent>
12+
13+
<packaging>maven-plugin</packaging>
14+
15+
<name>fj-doc-maven-plugin</name>
16+
17+
<description>Maven plugin to add Fugerit Venus Doc to a mavne project (fj-doc:generate)</description>
18+
19+
<properties>
20+
<mvn-site-plugin-version>3.12.1</mvn-site-plugin-version>
21+
<mvn-project-info-reports-plugin>3.6.0</mvn-project-info-reports-plugin>
22+
<!-- 'report' goal seems not to work with lastest version, 3.9.0 -->
23+
<mvn-plugin-version>3.13.1</mvn-plugin-version>
24+
</properties>
25+
26+
<licenses>
27+
<license>
28+
<name>Apache License, Version 2.0</name>
29+
<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
30+
<distribution>repo</distribution>
31+
</license>
32+
</licenses>
33+
34+
<build>
35+
36+
<pluginManagement>
37+
<plugins>
38+
<plugin>
39+
<groupId>org.apache.maven.plugins</groupId>
40+
<artifactId>maven-plugin-plugin</artifactId>
41+
<version>${mvn-plugin-version}</version>
42+
</plugin>
43+
<plugin>
44+
<groupId>org.apache.maven.plugins</groupId>
45+
<artifactId>maven-site-plugin</artifactId>
46+
<version>${mvn-site-plugin-version}</version>
47+
</plugin>
48+
<plugin>
49+
<groupId>org.apache.maven.plugins</groupId>
50+
<artifactId>maven-project-info-reports-plugin</artifactId>
51+
<version>${mvn-project-info-reports-plugin}</version>
52+
</plugin>
53+
</plugins>
54+
</pluginManagement>
55+
56+
</build>
57+
58+
<dependencies>
59+
60+
<dependency>
61+
<groupId>org.apache.maven</groupId>
62+
<artifactId>maven-plugin-api</artifactId>
63+
<scope>provided</scope>
64+
</dependency>
65+
66+
<dependency>
67+
<groupId>org.apache.maven.plugin-tools</groupId>
68+
<artifactId>maven-plugin-annotations</artifactId>
69+
</dependency>
70+
71+
<dependency>
72+
<groupId>org.fugerit.java</groupId>
73+
<artifactId>fj-core</artifactId>
74+
</dependency>
75+
76+
<dependency>
77+
<groupId>org.fugerit.java</groupId>
78+
<artifactId>fj-doc-freemarker</artifactId>
79+
</dependency>
80+
81+
<dependency>
82+
<groupId>org.maxxq.maven</groupId>
83+
<artifactId>maxxq-maven</artifactId>
84+
<version>1.3.0</version>
85+
</dependency>
86+
87+
</dependencies>
88+
89+
<organization>
90+
<url>https://www.fugerit.org</url>
91+
<name>Fugerit</name>
92+
</organization>
93+
94+
<url>https://www.fugerit.org/perm/venus</url>
95+
96+
<reporting>
97+
<plugins>
98+
<plugin>
99+
<groupId>org.apache.maven.plugins</groupId>
100+
<artifactId>maven-plugin-plugin</artifactId>
101+
<reportSets>
102+
<reportSet>
103+
<reports>
104+
<report>report</report>
105+
</reports>
106+
</reportSet>
107+
</reportSets>
108+
</plugin>
109+
</plugins>
110+
</reporting>
111+
112+
</project>

‎fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/maven/MojoAdd.java

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
package org.fugerit.java.doc.maven;
2+
3+
import org.apache.maven.plugin.AbstractMojo;
4+
import org.apache.maven.plugin.MojoExecutionException;
5+
import org.apache.maven.plugin.MojoFailureException;
6+
import org.apache.maven.plugins.annotations.Mojo;
7+
import org.apache.maven.plugins.annotations.Parameter;
8+
import org.fugerit.java.doc.project.facade.AddVenusFacade;
9+
import org.fugerit.java.doc.project.facade.VenusContext;
10+
11+
import java.io.File;
12+
13+
@Mojo( name = "add" )
14+
public class MojoAdd extends AbstractMojo {
15+
16+
@Parameter(property = "version", defaultValue = "8.5.2", required = true)
17+
protected String version;
18+
19+
@Parameter(property = "extensions", defaultValue = "base,freemarker", required = true)
20+
protected String extensions;
21+
22+
@Parameter(property = "projectFolder", defaultValue = ".", required = true)
23+
protected String projectFolder;
24+
25+
@Parameter(property = "addDocFacade", defaultValue = "true", required = true)
26+
protected boolean addDocFacade;
27+
28+
@Override
29+
public void execute() throws MojoExecutionException, MojoFailureException {
30+
VenusContext context = new VenusContext( new File( this.projectFolder ), this.version ,this.extensions );
31+
context.setAddDocFacace( this.addDocFacade );
32+
this.getLog().info( String.format( "add execute() context : %s", context ) );
33+
AddVenusFacade.addVenusToMavenProject( context );
34+
}
35+
36+
}

‎fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/AddVenusFacade.java

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
package org.fugerit.java.doc.project.facade;
2+
3+
import freemarker.cache.ClassTemplateLoader;
4+
import freemarker.cache.StringTemplateLoader;
5+
import freemarker.template.*;
6+
import lombok.extern.slf4j.Slf4j;
7+
import org.apache.maven.model.Dependency;
8+
import org.apache.maven.model.DependencyManagement;
9+
import org.apache.maven.model.Model;
10+
import org.fugerit.java.core.cfg.ConfigException;
11+
import org.fugerit.java.core.function.SafeFunction;
12+
import org.fugerit.java.core.io.FileIO;
13+
import org.fugerit.java.core.io.StreamIO;
14+
import org.fugerit.java.core.javagen.JavaGenerator;
15+
import org.fugerit.java.core.javagen.SimpleJavaGenerator;
16+
import org.fugerit.java.core.lang.helpers.ClassHelper;
17+
import org.fugerit.java.doc.freemarker.config.FreeMarkerConfigStep;
18+
import org.fugerit.java.doc.freemarker.fun.SimpleMessageFun;
19+
import org.fugerit.java.doc.freemarker.process.FreemarkerDocProcessConfig;
20+
import org.fugerit.java.doc.freemarker.process.FreemarkerDocProcessConfigFacade;
21+
import org.maxxq.maven.dependency.ModelIO;
22+
23+
import java.io.*;
24+
import java.nio.charset.StandardCharsets;
25+
import java.util.*;
26+
import java.util.stream.Collectors;
27+
28+
@Slf4j
29+
public class AddVenusFacade extends BasicVenusFacade {
30+
31+
private AddVenusFacade() {}
32+
33+
private static final String EXAMPLE_FOLDER = "config/example/";
34+
35+
private static void addDocFacade( VenusContext context ) throws IOException, TemplateException, ConfigException {
36+
// freemarker configuration
37+
Configuration configuration = new Configuration( new Version( FreeMarkerConfigStep.ATT_FREEMARKER_CONFIG_KEY_VERSION_LATEST ) );
38+
configuration.clearTemplateCache();
39+
ClassTemplateLoader loader = new ClassTemplateLoader( AddVenusFacade.class, "/config/template/" );
40+
configuration.setTemplateExceptionHandler( TemplateExceptionHandler.RETHROW_HANDLER );
41+
configuration.setTemplateLoader( loader );
42+
configuration.setDefaultEncoding(StandardCharsets.UTF_8.name());
43+
// config generation
44+
Template fmConfigTemplate = configuration.getTemplate( "fm-doc-process-config-template.ftl" );
45+
Map<Object, Object> data = new HashMap<>();
46+
data.put( "context" , context );
47+
File fmConfigFile = new File( context.getProjectDir(), "src/main/resources/"+context.getResourcePathFmConfigXml() );
48+
log.info( "fmConfigFile : {}, mk parent? : {}", fmConfigFile.getCanonicalPath(), fmConfigFile.getParentFile().mkdirs() );
49+
File templateDir = new File( fmConfigFile.getParentFile(), context.getTemplateSubPath() );
50+
log.info( "templateDir : {}, mk parent? : {}", templateDir.getCanonicalPath(), templateDir.mkdirs() );
51+
try ( Writer writer = new FileWriter( fmConfigFile ) ) {
52+
fmConfigTemplate.process( data, writer );
53+
}
54+
configuration.clearTemplateCache();
55+
// copy sample template
56+
String fileName = "document.ftl";
57+
File documentExample = new File( templateDir, fileName );
58+
try ( InputStream documentExampleIS = ClassHelper.loadFromDefaultClassLoader( EXAMPLE_FOLDER+fileName ) ) {
59+
String documentContent = StreamIO.readString( documentExampleIS );
60+
FileIO.writeString( documentContent, documentExample );
61+
}
62+
// create doc config
63+
File sourceFolder = new File( context.getProjectDir(), "src/main/java" );
64+
log.info( "sourceFolder : {}, mk parent? : {}", sourceFolder.getCanonicalPath(), sourceFolder.mkdirs() );
65+
File resourceFolder = new File( context.getProjectDir(), "src/main/resources" );
66+
log.info( "resourceFolder : {}, mk parent? : {}", resourceFolder.getCanonicalPath(), resourceFolder.mkdirs() );
67+
DocConfigGenerator javaGenerator = new DocConfigGenerator( context );
68+
Properties generatorProps = new Properties();
69+
javaGenerator.init( sourceFolder, context.getDocConfigPackage()+"."+context.getDocConfigClass(), SimpleJavaGenerator.STYLE_CLASS, generatorProps);
70+
javaGenerator.generate();
71+
javaGenerator.write();
72+
// create examples
73+
String docExampleFileName = "DocHelperExample.java";
74+
try ( InputStream documentExampleIS = ClassHelper.loadFromDefaultClassLoader( EXAMPLE_FOLDER+docExampleFileName ) ) {
75+
String documentContent = StreamIO.readString( documentExampleIS ).replace( "[PACKAGE]", context.getDocConfigPackage() );
76+
File docExampleFile = new File( new File( sourceFolder, context.getDocConfigPackage().replace( '.', '/' ) ), docExampleFileName );
77+
FileIO.writeString( documentContent, docExampleFile );
78+
}
79+
if ( context.getModules().contains( "fj-doc-mod-fop" ) ) {
80+
String fopConfigName = "fop-config.xml";
81+
File fopConfig = new File( new File( resourceFolder, context.getArtificatIdForFolder() ), fopConfigName );
82+
try ( InputStream fopConfigExampleIS = ClassHelper.loadFromDefaultClassLoader( EXAMPLE_FOLDER+fopConfigName ) ) {
83+
String fopConfigContent = StreamIO.readString( fopConfigExampleIS );
84+
FileIO.writeString( fopConfigContent, fopConfig );
85+
}
86+
}
87+
}
88+
89+
public static boolean addVenusToMavenProject( VenusContext context ) {
90+
return SafeFunction.get( () -> {
91+
File pomFile = new File( context.getProjectDir(), "pom.xml" );
92+
log.info( "project dir : {}", context.getProjectDir().getCanonicalPath() );
93+
if ( pomFile.exists() ) {
94+
addExtensionList( pomFile, context );
95+
if ( context.isAddDocFacace() ) {
96+
addDocFacade( context );
97+
}
98+
} else {
99+
addErrorAndLog( String.format( "No pom file in project dir : %s", pomFile.getCanonicalPath() ), context );
100+
return false;
101+
}
102+
return true;
103+
} );
104+
}
105+
106+
}
107+
108+
class DocConfigGenerator extends SimpleJavaGenerator {
109+
110+
private VenusContext context;
111+
112+
public DocConfigGenerator(VenusContext context) {
113+
this.context = context;
114+
}
115+
116+
@Override
117+
public void init(File sourceFolder, String fullObjectBName, String javaStyle, Properties config) throws ConfigException {
118+
super.init(sourceFolder, fullObjectBName, javaStyle, config);
119+
this.setNoCustomComment( true );
120+
this.getImportList().add( FreemarkerDocProcessConfig.class.getName() );
121+
this.getImportList().add( FreemarkerDocProcessConfigFacade.class.getName() );
122+
}
123+
124+
@Override
125+
public void generateBody() throws IOException {
126+
this.println( " private FreemarkerDocProcessConfig docProcessConfig = FreemarkerDocProcessConfigFacade.loadConfigSafe( \"cl://"+this.context.getResourcePathFmConfigXml()+"\" );" );
127+
this.println();
128+
this.println( " public FreemarkerDocProcessConfig getDocProcessConfig() { return this.docProcessConfig; }" );
129+
this.println();
130+
}
131+
132+
}

0 commit comments

Comments
 (0)