Skip to content

Commit

Permalink
202 fj doc guide fugerit venus doc documentation module (#210)
Browse files Browse the repository at this point in the history 
* [fj-doc-maven-plugin] goal init, flavour micronaut, default micronaut version 4.6.3

* Fix log doc xml validation

* Asciidoc documentation setup

* Asciidoc github pages  workflow

* Added legacy jekyll generation

* Quickstart and maven plugin chapters

* The doc format

* [#doc-format-entry-point]

* Doc entry point

* Anchors

* Anchors

* Freemarker generation

* Cambio snapshot

* Section 4 - dynamic data model

* Fix snapshot

* Doc Handler section

* guide build on main
  • Loading branch information
@fugerit79
fugerit79 authored Oct 11, 2024
1 parent 4f2f096 commit 6d0e0ed
Show file tree
Hide file tree
Showing 27 changed files with 1,333 additions and 2 deletions.
78 changes: 78 additions & 0 deletions .github/workflows/asciidoc_2_gh_pages.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# Simple workflow for deploying static content to GitHub Pages
name: Build and deploy AsciiDoc to GH Pages

on:
# Runs on pushes targeting the default branch
push:
branches: ["main"]

# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false

jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@main

- name: Setup JDK 21
uses: actions/setup-java@main
with:
java-version: 21
distribution: 'corretto'
cache: maven

- name: Set up Node.js
uses: actions/setup-node@main
with:
node-version: '20' # Puoi scegliere la versione di Node.js desiderata

- name: Install Mermaid CLI
run: npm install -g @mermaid-js/mermaid-cli

- name: Verify Mermaid CLI installation
run: mmdc --version

- name: Convert AsciiDoc to HTML5
run: cd fj-doc-guide;mvn clean asciidoctor:process-asciidoc@asciidoc-to-html

- name: Build Legacy Pages
uses: actions/jekyll-build-pages@main
with:
destination: "./fj-doc-guide/target/legacy/"

- name: Copy legacy site
run: cp -fr ./fj-doc-guide/target/legacy/ ./fj-doc-guide/target/site/

- name: Copy new site
run: cp -fr ./fj-doc-guide/target/generated-html5/ ./fj-doc-guide/target/site/guide/

- name: Setup Pages
uses: actions/configure-pages@main

- name: Upload artifact
uses: actions/upload-pages-artifact@main
with:
# Upload entire repository
path: './fj-doc-guide/target/site'

- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@main
10 changes: 10 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Fixed

- [fj-doc-base] Fix log doc xml validation

## [8.8.9] - 2024-09-27

### Changed

- [fj-doc-maven-plugin] goal init, flavour micronaut, default micronaut version 4.6.3

## [8.8.9] - 2024-09-27

### Changed
Expand Down
2 changes: 2 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ Framework to produce documents in different output formats starting from an XML
[![Online playground](https://img.shields.io/badge/Try%20Now-Online%20Playground-1AC736?style=for-the-badge&logo=Onlinect%20Playground&logoColor=white)](https://docs.fugerit.org/fj-doc-playground/home/)
[![Fugerit Github Project Conventions](https://img.shields.io/badge/Fugerit%20Org-Project%20Conventions-1A36C7?style=for-the-badge&logo=Onlinect%20Playground&logoColor=white)](https://universe.fugerit.org/src/docs/conventions/index.html)

[![view - Guide](https://img.shields.io/badge/view-Guide-blue?style=for-the-badge)](https://venusdocs.fugerit.org/guide/ "Go to project documentation")

The Core library (fj-doc-base) is all you need to start, even though typically you will use at least :
* [fj-doc-base](fj-doc-base/README.md)
* [fj-doc-freemarker](fj-doc-freemarker/README.md)
Expand Down
2 changes: 1 addition & 1 deletion fj-doc-base/src/main/java/org/fugerit/java/doc/base/xml/DocValidator.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ public static void logResult( SAXParseResult result, Logger logger ) throws XMLE
try ( PrintStream ps = new PrintStream( baos ) ) {
result.printErrorReport( ps );
if ( logger.isInfoEnabled() ) {
logger.info( "Validation issues : \n{}", String.valueOf( baos.toByteArray() ) );
logger.info( "Validation issues : \n{}", new String( baos.toByteArray() ) );
}
}
} );
Expand Down
247 changes: 247 additions & 0 deletions fj-doc-guide/pom.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,247 @@
<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-guide</artifactId>

<parent>
<groupId>org.fugerit.java</groupId>
<artifactId>fj-doc</artifactId>
<version>8.8.10-SNAPSHOT</version>
</parent>

<name>fj-doc-guide</name>
<description>Guide project for Fugerit Venus Doc</description>

<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>

<properties>
<!-- asciidoc properties -->
<asciidoctor.maven.plugin.version>3.0.0</asciidoctor.maven.plugin.version>
<asciidoctorj.pdf.version>2.3.15</asciidoctorj.pdf.version>
<asciidoctorj.version>2.5.12</asciidoctorj.version>
<asciidoctorj.diagram.version>2.3.0</asciidoctorj.diagram.version>
<asciidoctorj.diagram-plantuml.version>1.2024.3</asciidoctorj.diagram-plantuml.version>
<asciidoctorj.diagram-ditaamini.version>1.0.3</asciidoctorj.diagram-ditaamini.version>
<jruby.version>9.4.6.0</jruby.version>
<maven.build.timestamp.format>yyyy-MM-dd'T'HH:mm:ss'Z'</maven.build.timestamp.format>
<pdf-output-folder>${project.build.directory}/generated-pdf</pdf-output-folder>
<html-output-folder>${project.build.directory}/generated-html5</html-output-folder>
</properties>

<build>
<defaultGoal>process-resources</defaultGoal>
<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}-${project.version}.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>
<configuration>
<backend>html5</backend>
<outputDirectory>${html-output-folder}</outputDirectory>
<!--
Scenarios for linking vs embedding assets:
Link to both stylesheets and images::
- don't set embedAssets option
- set linkcss attribute to true
- set imagesdir attribute to path relative to AsciiDoc source file
<attributes>
<linkcss>true</linkcss>
<imagesdir>./images</imagesdir>
</attributes>
Embed stylesheets and images::
- set embedAssets option to true
- don't set linkcss attribute
- set imagesdir attribute to path relative to project root
<embedAssets>true</embedAssets>
<attributes>
<imagesdir>src/docs/asciidoc/images</imagesdir>
</attributes>
Link to stylesheets but embed images::
- set embedAssets option to true
- set linkcss attribute to true
- set imagesdir attribute to path relative to project root
<embedAssets>true</embedAssets>
<attributes>
<linkcss>true</linkcss>
<imagesdir>src/docs/asciidoc/images</imagesdir>
</attributes>
Embed stylesheets but link images (default)::
- don't set embedAssets option
- don't set linkcss attribute
- set imagesdir attribute to path relative to AsciiDoc source file
<attributes>
<imagesdir>./images</imagesdir>
</attributes>
IMPORTANT: When you enable image embedding, you must qualify the path with imagesdir, as shown above.
-->
<attributes>
<source-highlighter>rouge</source-highlighter>
<imagesdir>resources/images</imagesdir>
<toc>left</toc>
<icons>font</icons>
<sectanchors>true</sectanchors>
<!-- set the idprefix to blank -->
<idprefix/>
<idseparator>-</idseparator>
<docinfo1>true</docinfo1>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>

<dependencies>

<dependency>
<groupId>org.fugerit.java</groupId>
<artifactId>fj-core</artifactId>
</dependency>

<dependency>
<groupId>org.fugerit.java</groupId>
<artifactId>fj-doc-base</artifactId>
</dependency>

<dependency>
<groupId>org.fugerit.java</groupId>
<artifactId>fj-doc-freemarker</artifactId>
</dependency>

<dependency>
<groupId>org.fugerit.java</groupId>
<artifactId>fj-test-helper8</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>*</groupId>
<artifactId>*</artifactId>
</exclusion>
</exclusions>
</dependency>

</dependencies>

<organization>
<url>https://www.fugerit.org</url>
<name>Fugerit</name>
</organization>

<url>https://www.fugerit.org/perm/venus/</url>

</project>
15 changes: 15 additions & 0 deletions fj-doc-guide/src/main/docs/asciidoc/attributes/_attributes-common.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
:author: Matteo Franci
:revnumber: v1.0.0
:revdate: June XX, 2024
:email: [email protected]
:description: This is a comparison of a simple online demo photobook \
implemented with three popular java cloud ready framework.
:keywords: java, graalvm, spring, springboot, quarkus, micronaut
:encoding: utf-8
:lang: en
:toc: left
:hardbreaks-option:
:sectnums:
:sectnumlevels: 3
:!figure-caption:
:!chapter-signifier:
1 change: 1 addition & 0 deletions fj-doc-guide/src/main/docs/asciidoc/attributes/_attributes-pdf.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
:doctype: book
Loading

0 comments on commit 6d0e0ed

Please sign in to comment.