Skip to content
This repository was archived by the owner on Oct 25, 2024. It is now read-only.

Commit 19bb5be

Browse files
fugerit79fugerit79
committed
Wizard section
1 parent 7042361 commit 19bb5be

File tree

5 files changed

+129
-0
lines changed

5 files changed

+129
-0
lines changed

‎README.md

+2
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ This projects provides simple guides to [Venus - Fugerit Document Generation Fra
1313

1414
## Index
1515

16+
A new [Wizard](src/docs/wizard/index.md) section is available, guiding you through some common scenarios.
17+
1618
### General topics
1719

1820
- [Venus Doc Format entry point](src/docs/common/doc_format_summary.md) - a starting point for writing the Venus XML meta model

‎src/docs/wizard/fj-doc-config_migration.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Configuration migration from DocProcessConfig to FreemarkerDocProcessConfig
2+
3+
[Index](index.md)
4+
5+
This guide is needed only if the old configurations files `doc-handler-facade.xml` and/or the `doc-process-config.xml` are being used.
6+
7+
If you are already using the new [freemarker-doc-process-1-0.xsd](https://github.com/fugerit-org/fj-doc/blob/main/fj-doc-freemarker/src/main/resources/config_fm_xsd/freemarker-doc-process-1-0.xsd) you do not need to read more.
8+
9+
At the beginning, Venus was using the [DocProcessConfig](https://github.com/fugerit-org/fj-doc/blob/c458ba4e54477a6db650dcc9f71fb2dab4c63bef/fj-doc-base/src/main/java/org/fugerit/java/doc/base/process/DocProcessConfig.java) facade to handle the generation pipeline.
10+
11+
Now it is strongly recommended to use the new [FreemarkerDocProcessConfig](https://github.com/fugerit-org/fj-doc/blob/main/fj-doc-freemarker/src/main/java/org/fugerit/java/doc/freemarker/process/FreemarkerDocProcessConfig.java) facade.
12+
13+
It substitutes both the `doc-handler-facade.xml` and the `doc-process-config.xml`.
14+
15+
The needed steps depends on the specific project configuration, but can be summarized in :
16+
17+
## 1. Convert the `doc-process-config.xml` and `doc-handler-facade.xml` in `freemarker-doc-process.xml`
18+
19+
You can use the [Doc Configuration Convert](https://docs.fugerit.org/fj-doc-playground/home) function from the online playground.
20+
21+
For instance starting from :
22+
23+
```xml
24+
<doc-process>
25+
26+
<chain id="test-chain">
27+
<step id="step-01" defaultBehaviour="CONTINUE"
28+
description="Test for coverage"
29+
type="test.org.fugerit.java.doc.base.coverage.ProcessStepCoverage"
30+
param01="TEST">
31+
<properties xmlPath="coverage/xml/default_doc_alt.xml"/>
32+
</step>
33+
</chain>
34+
35+
</doc-process>
36+
```
37+
38+
```xml
39+
<doc-handler-config user-catalog="default-complete">
40+
41+
<factory id="default-complete">
42+
<data id="md-ext" info="md" type="org.fugerit.java.doc.base.typehandler.markdown.SimpleMarkdownExtTypeHandler" />
43+
</factory>
44+
45+
</doc-handler-config>
46+
```
47+
48+
The resulting `freemarker-doc-process.xml` should be :
49+
50+
```xml
51+
<?xml version="1.0" encoding="utf-8"?>
52+
<freemarker-doc-process-config
53+
xmlns="https://freemarkerdocprocess.fugerit.org"
54+
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" >
56+
57+
<docHandlerConfig>
58+
<!-- Type handler for markdown format -->
59+
<docHandler id="md-ext" info="md" type="org.fugerit.java.doc.base.typehandler.markdown.SimpleMarkdownExtTypeHandler" />
60+
61+
</docHandlerConfig>
62+
63+
<docChain id="test-chain">
64+
<chainStep stepType="test.org.fugerit.java.doc.base.coverage.ProcessStepCoverage">
65+
<!-- custom step, additional configuration may be needed -->
66+
</chainStep>
67+
</docChain>
68+
69+
</freemarker-doc-process-config>
70+
```
71+
72+
## 2. Create your FreemarkerDocProcessConfig instance
73+
74+
```java
75+
FreemarkerDocProcessConfig config = FreemarkerDocProcessConfigFacade.loadConfigSafe("cl://path/to/freemarker-doc-process.xml" );
76+
```
77+
## 3. Use new fullProcess() functions
78+
79+
```java
80+
String chainId = "test-chain";
81+
DocProcessContext context = DocProcessContext.newContext( ... );
82+
String type = "md";
83+
FreemarkerDocProcessConfig config = FreemarkerDocProcessConfigFacade.loadConfigSafe("cl://path/to/freemarker-doc-process.xml" );
84+
config.fullProcess( chainId, context, type, outputStream );
85+
```
86+
## 4. Any needed clean up
87+
88+
Remove your old `doc-process-config.xml` configuration and any obsolete file and method.

‎src/docs/wizard/fj-doc-maven-plugin_add.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Add venus configuration and sample to an existing maven project
2+
3+
[Index](index.md)
4+
5+
It is possible to use the `org.fugerit.java:fj-doc-maven-plugin:add` to Venus configuration to an existing maven project.
6+
7+
Just run this command inside the directory where the `pom.xml` is located :
8+
9+
```shell
10+
mvn org.fugerit.java:fj-doc-maven-plugin:add \
11+
-Dextensions=base,freemarker,mod-fop
12+
```
13+
14+
For additional options see [documentation](https://github.com/fugerit-org/fj-doc/blob/main/fj-doc-maven-plugin/README.md#goal--add).

‎src/docs/wizard/fj-doc-maven-plugin_init.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Creates a new project already configured for Venus
2+
3+
[Index](index.md)
4+
5+
It is possible to use the `org.fugerit.java:fj-doc-maven-plugin:init` maven plugin in order initialize a new project, it is as simple as running :
6+
7+
```shell
8+
mvn org.fugerit.java:fj-doc-maven-plugin:init \
9+
-DgroupId=org.example.doc \
10+
-DartifactId=fugerit-demo
11+
```
12+
13+
A new folder `$artifactId` folder will be created, containing the maven project configured for using Venus.
14+
15+
For additional options see [documentation](https://github.com/fugerit-org/fj-doc/blob/main/fj-doc-maven-plugin/README.md#goal--init).

‎src/docs/wizard/index.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Venus Wizard and Use Cases
2+
3+
[Index](../../../README.md)
4+
5+
This sections includes some common scenarios in using [Fugerit Doc Venus](https://github.com/fugerit-org/fj-doc), organized as a wizard.
6+
7+
Main scenarios
8+
- [Creates a new project already configured for Venus](fj-doc-maven-plugin_init.md)
9+
- [Add venus configuration and sample to an existing maven project](fj-doc-maven-plugin_add.md)
10+
- [Configuration migration from DocProcessConfig to FreemarkerDocProcessConfig](fj-doc-config_migration.md)

0 commit comments

Comments
 (0)