Quarkus Event Bus Logging Filter JAX-RS Documentation

The Document as Code (doc-as-code) approach applies software development principles to the creation, management, and distribution of documentation. This method aims to improve the quality, efficiency, and agility of documentation production by treating documents as part of the project’s source code.

This fosters a culture of documentation that is agilely integrated with software development, allowing for a more efficient workflow, higher quality documentation, and a better overall experience for developers and end users.

This repository contains the source code of the Quarkus Event Bus Logging Filter JAX-RS eBook, illustrating how the project was created and published on GitHub.

The project was developed using the Document as Code (doc-as-code) approach, using AsciiDoc, a lightweight markup language for writing human-readable and machine-readable documents.

The toolchain used for generating the eBook is Asciidoctor, a text processor supporting AsciiDoc syntax that produces HTML5, DocBook, PDF, and other formats.

Supported outputs for this documentation are: html5 and pdf.

The project uses the Asciidoctor Maven Plugin, responsible for processing source files in AsciiDoc format and generating the eBook in PDF format.

Requirements

To generate documentation in the supported formats, the following software needs to be installed on your system (development workstation or CI/CD):

• Java JDK 11 or higher
• Maven 3.8.x or higher
• Mermaid CLI 10.8.4 or higher

Mermaid CLI is a tool for generating flowcharts, sequence diagrams, Gantt charts, and class diagrams from source code; some diagrams in the documentation are generated using Mermaid.

Install this tool via the npm package manager, requiring Node.js (version ^14.13 || >=16.0).

npm install -g @mermaid-js/mermaid-cli

Console 0 - Install Mermaid CLI

Generating the eBook

To generate the eBook in PDF format, run the Maven command:

mvn clean asciidoctor:process-asciidoc@asciidoc-to-pdf

Console 1 - Execute the Maven command to generate the eBook

The Maven command will compile the project and generate the PDF eBook. The generated PDF file will be available in the project’s target/generated-pdf folder, named ${project.artifactId}-${project.version}.pdf.

Generating HTML Documentation

To generate HTML documentation, run the Maven command:

mvn clean asciidoctor:process-asciidoc@asciidoc-to-html

Console 2 - Execute the Maven command to generate the HTML docs

The Maven command will compile the project and generate the HTML documentation. The HTML documentation will be available in the project’s target/generated-html5 folder.

Publishing HTML Documentation on GitHub Pages

The generated HTML documentation is also available on GitHub Pages. This is made possible by the GitHub Actions Deploy AsciiDoc to Pages, which publishes the generated HTML documentation (via the AsciiDoc Maven plugin) to GitHub Pages.