https://github.com/amusarra/eventbus-logging-filter-jaxrs-docs
Doc-as-Code project for the eBook Quarkus Event Bus Logging Filter JAX-RS
https://github.com/amusarra/eventbus-logging-filter-jaxrs-docs
asciidoc event-bus java jax-rs quarkus
Last synced: over 1 year ago
JSON representation
Doc-as-Code project for the eBook Quarkus Event Bus Logging Filter JAX-RS
- Host: GitHub
- URL: https://github.com/amusarra/eventbus-logging-filter-jaxrs-docs
- Owner: amusarra
- License: other
- Created: 2024-04-22T18:17:08.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-18T21:25:34.000Z (about 2 years ago)
- Last Synced: 2025-04-12T05:45:29.660Z (over 1 year ago)
- Topics: asciidoc, event-bus, java, jax-rs, quarkus
- Homepage: https://amusarra.github.io/eventbus-logging-filter-jaxrs-docs/
- Size: 9.1 MB
- Stars: 4
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Quarkus Event Bus Logging Filter JAX-RS Documentation
[](CHANGELOG.md)
[](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.it)
[](https://github.com/amusarra/eventbus-logging-filter-jaxrs-docs/actions/workflows/build_asciidoc_to_pdf.yml)
[](https://github.com/amusarra/eventbus-logging-filter-jaxrs-docs/actions/workflows/build_asciidoc_to_html_github_page.yml)
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](https://github.com/amusarra/eventbus-logging-filter-jaxrs) 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](https://asciidoc.org/), a lightweight markup language for writing human-readable and machine-readable documents.
The toolchain used for generating the eBook is [Asciidoctor](https://asciidoctor.org/), 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](https://asciidoctor.org/docs/asciidoctor-maven-plugin/) 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](https://www.npmjs.com/package/@mermaid-js/mermaid-cli?activeTab=readme) 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).
```shell script
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:
```shell script
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:
```shell script
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](https://amusarra.github.io/eventbus-logging-filter-jaxrs-docs/). This is made possible by the GitHub Actions [Deploy AsciiDoc to Pages](.github/workflows/build_asciidoc_to_html_github_page.yml), which publishes the generated HTML documentation (via the AsciiDoc Maven plugin) to GitHub Pages.