Add asciidoc documentation #265

.gitignore

@@ -106,3 +106,4 @@ buildNumber.properties
 # End of https://www.gitignore.io/api/java,maven,eclipse
 
 /.apt_generated/
+/fj-doc-playground-quarkus/src/main/react/public/help/

fj-doc-playground-quarkus/pom.xml

@@ -301,15 +301,161 @@
 			</build>
 		</profile>	
 
-
 		<profile>
 
 			<id>buildreact</id>
 
+			<properties>
+				<!-- asciidoc properties -->
+				<asciidoctor.maven.plugin.version>3.1.1</asciidoctor.maven.plugin.version>
+				<asciidoctorj.pdf.version>2.3.19</asciidoctorj.pdf.version>
+				<asciidoctorj.version>3.0.0</asciidoctorj.version>
+				<asciidoctorj.diagram.version>2.3.1</asciidoctorj.diagram.version>
+				<asciidoctorj.diagram-plantuml.version>1.2024.5</asciidoctorj.diagram-plantuml.version>
+				<asciidoctorj.diagram-ditaamini.version>1.0.3</asciidoctorj.diagram-ditaamini.version>
+				<jruby.version>9.4.9.0</jruby.version>
+				<maven.build.timestamp.format>yyyy-MM-dd'T'HH:mm:ss'Z'</maven.build.timestamp.format>
+				<html-output-folder-no-toc>${project.basedir}/src/main/react/public/help</html-output-folder-no-toc>
+				<pdf-output-folder>${html-output-folder-no-toc}</pdf-output-folder>
+			</properties>
+
 			<build>
 
 				<plugins>
 
+					<plugin>
+						<groupId>org.asciidoctor</groupId>
+						<artifactId>asciidoctor-maven-plugin</artifactId>
+						<version>${asciidoctor.maven.plugin.version}</version>
+						<dependencies>
+							<dependency>
+								<groupId>org.asciidoctor</groupId>
+								<artifactId>asciidoctorj-pdf</artifactId>
+								<version>${asciidoctorj.pdf.version}</version>
+							</dependency>
+							<!-- Comment this section to use the default jruby artifact provided by the plugin -->
+							<dependency>
+								<groupId>org.jruby</groupId>
+								<artifactId>jruby</artifactId>
+								<version>${jruby.version}</version>
+							</dependency>
+							<!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
+							<dependency>
+								<groupId>org.asciidoctor</groupId>
+								<artifactId>asciidoctorj</artifactId>
+								<version>${asciidoctorj.version}</version>
+							</dependency>
+							<dependency>
+								<groupId>org.asciidoctor</groupId>
+								<artifactId>asciidoctorj-diagram</artifactId>
+								<version>${asciidoctorj.diagram.version}</version>
+							</dependency>
+							<dependency>
+								<groupId>org.asciidoctor</groupId>
+								<artifactId>asciidoctorj-diagram-plantuml</artifactId>
+								<version>${asciidoctorj.diagram-plantuml.version}</version>
+							</dependency>
+							<dependency>
+								<groupId>org.asciidoctor</groupId>
+								<artifactId>asciidoctorj-diagram-ditaamini</artifactId>
+								<version>${asciidoctorj.diagram-ditaamini.version}</version>
+							</dependency>
+						</dependencies>
+						<configuration>
+							<requires>
+								<require>asciidoctor-diagram</require>
+							</requires>
+							<resources>
+								<resource>
+									<directory>src/main/docs/asciidoc</directory>
+									<excludes>
+										<exclude>resources/themes/**</exclude>
+									</excludes>
+								</resource>
+							</resources>
+							<sourceDirectory>src/main/docs/asciidoc</sourceDirectory>
+							<enableVerbose>true</enableVerbose>
+							<logHandler>
+								<outputToConsole>true</outputToConsole>
+							</logHandler>
+							<!-- Attributes common to all output formats -->
+							<attributes>
+								<attribute-missing>warn</attribute-missing>
+								<allow-uri-read>true</allow-uri-read>
+								<source-highlighter>rouge</source-highlighter>
+								<imagesdir>./resources/images</imagesdir>
+								<themesdir>./resources/themes</themesdir>
+								<revnumber>${project.version}</revnumber>
+								<revdate>${maven.build.timestamp}</revdate>
+								<revremark>Digital Version</revremark>
+								<organization>${project.organization.name}</organization>
+							</attributes>
+						</configuration>
+						<executions>
+							<execution>
+								<id>asciidoc-to-pdf</id>
+								<phase>generate-resources</phase>
+								<goals>
+									<goal>process-asciidoc</goal>
+								</goals>
+								<configuration>
+									<backend>pdf</backend>
+									<doctype>book</doctype>
+									<sourceDocumentName>index.adoc</sourceDocumentName>
+									<outputDirectory>${pdf-output-folder}</outputDirectory>
+									<outputFile>${project.artifactId}.pdf</outputFile>
+									<attributes>
+										<pdf-theme>basic</pdf-theme>
+										<pdf-themesdir>${project.basedir}/src/main/docs/asciidoc/resources/themes</pdf-themesdir>
+										<icons>font</icons>
+										<pagenums/>
+										<toc/>
+										<idprefix/>
+										<idseparator>-</idseparator>
+									</attributes>
+								</configuration>
+							</execution>
+							<execution>
+								<id>asciidoc-to-html</id>
+								<phase>generate-resources</phase>
+								<goals>
+									<goal>process-asciidoc</goal>
+								</goals>
+							</execution>
+							<execution>
+								<id>asciidoc-to-html-no-toc</id>
+								<phase>generate-resources</phase>
+								<goals>
+									<goal>process-asciidoc</goal>
+								</goals>
+								<configuration>
+									<backend>html5</backend>
+									<outputDirectory>${html-output-folder-no-toc}</outputDirectory>
+									<resources>
+										<resource>
+											<directory>src/main/docs/asciidoc/features/</directory>
+											<excludes>
+												<exclude>resources/themes/**</exclude>
+											</excludes>
+										</resource>
+									</resources>
+									<sourceDirectory>src/main/docs/asciidoc/features/</sourceDirectory>
+									<attributes>
+										<source-highlighter>rouge</source-highlighter>
+										<imagesdir>resources/images</imagesdir>
+										<icons>font</icons>
+										<no-toc/>
+										<sectanchors>true</sectanchors>
+										<!-- set the idprefix to blank -->
+										<idprefix/>
+										<idseparator>-</idseparator>
+										<docinfo1>true</docinfo1>
+									</attributes>
+								</configuration>
+							</execution>
+						</executions>
+					</plugin>
+
 					<plugin>
 						<groupId>org.codehaus.mojo</groupId>
 						<artifactId>exec-maven-plugin</artifactId>

fj-doc-playground-quarkus/src/main/docs/asciidoc/attributes/_attributes-common.adoc

@@ -0,0 +1,14 @@
+:author: Matteo Franci
+:revnumber: v1.0.0
+:revdate: October 15, 2024
+:email: m@fugerit.org
+:description: Venus Online Playground Guide
+:keywords: java, xml, json, yaml, kotlin, pdf, html, xlsx, csv, document generation
+:encoding: utf-8
+:lang: en
+:toc: left
+:hardbreaks-option:
+:sectnums:
+:sectnumlevels: 3
+:!figure-caption:
+:!chapter-signifier:

fj-doc-playground-quarkus/src/main/docs/asciidoc/attributes/_attributes-pdf.adoc

@@ -0,0 +1 @@
+:doctype: book

fj-doc-playground-quarkus/src/main/docs/asciidoc/features/doc-config-convert.adoc

@@ -0,0 +1,90 @@
+
+<<<
+[#doc-playground-config-convert]
+== Doc Config Conversion tool
+
+link:https://github.com/fugerit-org/fj-doc[Venus Project] use to have a different configuration setup in teh past
+(previous to version 1.3).
+
+This configuration is still supported, but it's now considered legacy. The *Doc Config Conversion tool* helps to convert the old configuration model to the new one.
+
+The old configuration model, consisted of two different XML files :
+
+=== 1. Doc Process Config File
+
+It starts with _<doc-process/>_ element and looks like :
+
+[source,xml]
+----
+<doc-process>
+	<chain id="shared">
+		<step id="step-01" defaultBehaviour="CONTINUE"
+			description="Apache FreeMarker Configuration"
+			type="org.fugerit.java.doc.freemarker.config.FreeMarkerConfigStep"
+			param01="FJ_DOC_LIB_AUTODOC">
+            <!-- more configuration -->
+		</step>
+    </chain>
+    <!-- more configuration -->
+</doc-process>
+----
+
+=== 2. Doc Handler Config file
+
+[source,xml]
+----
+<doc-handler-config user-catalog="default-complete">
+
+	<factory id="unsafe-test">
+		<data id="html-fm" info="html" type="org.fugerit.java.doc.freemarker.html.FreeMarkerHtmlTypeHandlerUTF8" />
+		<data id="html-fragment-fm" info="fhtml" type="org.fugerit.java.doc.freemarker.html.FreeMarkerHtmlFragmentTypeHandlerUTF8" />
+	</factory>
+
+</doc-handler-config>
+----
+
+The Doc Configuration conversion tool, accept as input the *Doc Process Config* XML file in the first text area, and some parameters in the second text area, like:
+
+[source,text]
+----
+# if stub handers=1, sample type handler configuration will be created
+stub-handler=1
+# docHandlerConfig attributes values
+registerById=true
+allowDuplicatedId=true
+----
+
+The result will be something like :
+
+[source,xml]
+----
+<?xml version="1.0" encoding="utf-8"?>
+<freemarker-doc-process-config
+xmlns="https://freemarkerdocprocess.fugerit.org"
+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" >
+
+	<docHandlerConfig registerById="true" allowDuplicatedId="true">
+		<!-- Type handler for markdown format -->
+		<docHandler id="md-ext" info="md" type="org.fugerit.java.doc.base.typehandler.markdown.SimpleMarkdownExtTypeHandler" />
+		<!-- Type henalder for xml format, generates the source xml:doc -->
+		<docHandler id="xml-doc" info="xml" type="org.fugerit.java.doc.base.config.DocTypeHandlerXMLUTF8" />
+
+		<!-- Type handlers for html using freemarker -->
+		<docHandler id="html-fm" info="html" type="org.fugerit.java.doc.freemarker.html.FreeMarkerHtmlTypeHandlerEscapeUTF8" />
+		<!-- Type handlers for html using freemarker (fragment version, only generates body content no html or head part -->
+		<docHandler id="html-fragment-fm" info="fhtml" type="org.fugerit.java.doc.freemarker.html.FreeMarkerHtmlFragmentTypeHandlerEscapeUTF8" />
+	</docHandlerConfig>
+
+
+	<docChain id="shared">
+		<chainStep stepType="config">
+			<config
+				id="FJ_DOC_LIB_AUTODOC"
+			/>
+		</chainStep>
+	</docChain>
+
+
+</freemarker-doc-process-config>
+----

fj-doc-playground-quarkus/src/main/docs/asciidoc/features/doc-conversion.adoc

@@ -0,0 +1,10 @@
+
+<<<
+[#doc-playground-conversion]
+== Doc Conversion (XML/JSON/YAML)
+
+This page allow conversion from/to XML/JSON/YAML format.
+
+It also allows pretty print.
+
+For istance it is possible to indent XML or JSON format.

fj-doc-playground-quarkus/src/main/docs/asciidoc/features/doc-generator.adoc

@@ -0,0 +1,38 @@
+
+<<<
+[#doc-playground-generator]
+== Doc Editor and Generator
+
+This tool is the core of the application. It gives you the change to really test the link:https://github.com/fugerit-org/fj-doc[Venus Document Generation Framework].
+
+=== 1. Pick a source type
+
+You can pick 5 source options (when choosing one the _Document samples catalog_ will automatically update with relevant examples) :
+
+. link:https://venusdocs.fugerit.org/guide/#doc-freemarker-entry-point[FTLX] - FreeMarker template XML _(*)_
+. link:https://venusdocs.fugerit.org/guide/#doc-format-entry-point-xml[XML]
+. link:https://venusdocs.fugerit.org/guide/#doc-format-entry-point-json-yaml[JSON]
+. link:https://venusdocs.fugerit.org/guide/#doc-format-entry-point-json-yaml[YAML]
+. link:https://venusdocs.fugerit.org/guide/#doc-format-entry-point-kotlin[KTS]
+(Kotlin)
+
+NOTE: _(*)_ Using a freemarker template to generate a link:https://venusdocs.fugerit.org/guide/#doc-format-entry-point[DOC XML Format] is the best supported scenario. Other input options are mainly for people not familiar with XML or Apache FreeMarker.
+
+=== 2. Pick an output format
+
+You can choose among multiple output format. Each based on a specific link:https://venusdocs.fugerit.org/guide/#doc-handler-module-handlers[Doc Handler].
+
+
+=== 3. Customize the input
+
+Creato or modify input source. (For FTLX and KTS add JSON data model if you want).
+
+=== 4. Generate document
+
+Click on the *Generate document*, usually preview or download options will be available.
+
+In case of error, a message will be shown.
+
+=== Extra : Validate document
+
+XML, JSON and YAML document support the _Validate document_ function.

fj-doc-playground-quarkus/src/main/docs/asciidoc/features/doc-project-init.adoc

@@ -0,0 +1,22 @@
+
+<<<
+[#doc-playground-project-init]
+== Doc Project Initialization
+
+This function is user interface for the link:https://venusdocs.fugerit.org/guide/#maven-plugin-goal-init[Venus Maven Plugin : Init Goal].
+
+For instance selecting :
+
+- *Group ID* : org.example.demo
+- *Artifact ID* : venus-demo
+- *Project Version* : 1.0.0
+- *Java Version* : 17
+- *Venus Version* : 8.11.2
+- *Flavour* : Quarkus 3
+- *Extensions* : fj-doc-base,fj-doc-freemarker,fj-doc-mod-fop (1)
+
+Will creates a new link:https://quarkus.io/[Quarkus 3] project with support and examples to generate documents in MarkDown, HTML, AsciiDOC, XSL-FO and PDF.
+
+The project will be a single zip containing a maven project and all the needed resource with a proof of concept document generation. (in a similar way to link:https://start.spring.io/[Spring Initializr] or link:https://code.quarkus.io/[Quarkus Project Launcher]).
+
+(1) Check the documentation to know which formats are supported by each link:https://venusdocs.fugerit.org/guide/#doc-handler-module-handlers[module].

fj-doc-playground-quarkus/src/main/docs/asciidoc/features/doc-type-validator.adoc

@@ -0,0 +1,11 @@
+
+<<<
+[#doc-playground-type-validator]
+== Doc Type Validator
+
+The Doc Type Validator helper, is a simple interface to test the
+link:https://github.com/fugerit-org/fj-doc/tree/main/fj-doc-val[Doc Type Validator modules].
+
+Simply upload a file (on the left) to check if it is valid according to one of the supported formats (on the right).
+
+NOTE: This is just a demo version. Currently really useful for any real scenario.

fj-doc-playground-quarkus/src/main/docs/asciidoc/features/home.adoc

@@ -0,0 +1,10 @@
+
+<<<
+[#doc-playground-home]
+== Playground for Venus - Fugerit Doc Generation Framework
+
+This is the link:https://github.com/fugerit-org/fj-doc[Venus] Online Playground.
+
+It is possible to run it locally too using the pre-buildt link:https://hub.docker.com/r/fugeritorg/fj-doc-playground-quarkus[Docker images].
+
+NOTE: for full documentation check the link:https://venusdocs.fugerit.org/guide/[online guide].

fj-doc-playground-quarkus/src/main/docs/asciidoc/index.adoc

@@ -0,0 +1,13 @@
+= Fugerit Online Playground Guide
+// format attributes inclusions
+include::attributes/_attributes-pdf.adoc[]
+include::attributes/_attributes-common.adoc[]
+
+// Chapters inclusions
+
+include::features/home.adoc[]
+
+
+include::features/doc-type-validator.adoc[]
+
+include::features/doc-config-convert.adoc[]

fj-doc-playground-quarkus/src/main/docs/asciidoc/resources/images/readme.txt

@@ -0,0 +1 @@
+images go here