search

jqassistant-archive / jqassistant-asciidoc-report-plugin

jQAssistant report plugin for rendering Asciidoc rule documents to HTML including results as tables and diagrams.
GNU General Public License v3.0
1 stars 3 forks source link
asciidoc jqassistant plantuml plugin report

readme

:toc: = jQAssistant Asciidoc Report Plugin

This project provides a http://jqassistant.org/[jQAssistant] report plugin for rendering http://www.methods.co.nz/asciidoc/[Asciidoc] documents containing rules and embedding their results.

NOTE: This repository has been archived as the plugin has been integrated into the jQAssistant main project: https://github.com/jQAssistant/jqa-asciidoc-report-plugin[].

== How It Works

The plugin records the results of executed rules (i.e. concepts and constraints). At the end of the analysis phase http://www.asciidoctor[Asciidoctor] is used for rendering the input documents providing the rules to HTML documents. The listings containing rules are identified and their status and results appended. Furthermore include directives are provided for embedding a summary about executed and imported rules.

TIP: You can find an example setup and rules in the http://github.com/buschmais/spring-petclinic/[Spring PetClinic] demo. After cloning the repository and building using mvn install the rendered report is available in the directory target/jqassistant/report/asciidoc.

== Prerequisites

== Setup

The plugin can be enabled in a Maven based project by adding it as a dependency to the jQAssistant Maven plugin:

.pom.xml [source,xml]

com.buschmais.jqassistant jqassistant-maven-plugin 1.6.0 default-cli scan analyze index.adoc --> org.jqassistant.contrib.plugin jqassistant-asciidoc-report-plugin 1.6.0
<1> Defines the directory where the source Asciidoc files are located (optional). <2> The filter specifying the source file which should be rendered (optional). <3> Declares the plugin as dependency for jQAssistant For using the plugin with the command line distribution download the JAR file from https://search.maven.org/search?q=a:jqassistant-asciidoc-report-plugin[Maven Central] and copy it to the `plugins/` folder. NOTE: By default all rule files with the name `index.adoc` will be selected for rendering. The report properties `asciidoc.report.rule.directory` and `asciidoc.report.file.include` may be used to explicitly select files. == Includes The report may be enhanced by `jQA` include directives: `jQA:Summary[]`:: Embeds a summary table containing all executed rules, their description and status. `jQA:ImportedRules[]`:: Renders descriptions for all rules which have been executed but which are not part of the document itself (i.e. provided by plugins). .jqassistant/index.adoc .... = My Project This document describes architectural and design rules for My Project. == Summary \include::jQA:Summary[] [[default]] [role=group,includesGroups="..."] == Rules ... project specific rules ... == Imported Rules \include::jQA:ImportedRules[] .... == Component Diagrams The plugin provides supports generating component diagrams from rule results. NOTE: This feature is based on http://plantuml.com/[PlantUML] which itself relies on http://www.graphviz.org[Graphviz]. The latter needs to be installed and the `dot` executable must be present on the system path. To activate diagram rendering the report type must be set to `plantuml-component-diagram`. The result of the rule simply needs to return all required nodes and their relationships: .jqassistant/index.adoc .... [[package:DependencyDiagram]] [source,cypher,role=concept,requiresConcepts="dependency:Package",reportType="plantuml-component-diagram"] // (1) .Creates a diagram about dependencies between packages containing Java types (test artifacts are excluded). ---- MATCH (artifact:Main:Artifact)-[:CONTAINS]->(package:Package)-[:CONTAINS]->(:Type) OPTIONAL MATCH (package)-[dependsOn:DEPENDS_ON]->(:Package) RETURN package, dependsOn // (2) ---- .... (1) The report type is set to `plantuml-component-diagram`. (2) The packages are returned as nodes and their dependencies (dependsOn) as relationships. The result might also specify graph-alike structures which will be rendered as PlantUML folders. The following example therefore uses a modified return clause: .jqassistant/index.adoc .... [[package:DependencyPerArtifactDiagram]] [source,cypher,role=concept,requiresConcepts="dependency:Package",reportType="plantuml-component-diagram"] .Creates a diagram about dependencies between packages containing Java types (per artifact, test artifacts are excluded). ---- MATCH (artifact:Main:Artifact)-[:CONTAINS]->(package:Package)-[:CONTAINS]->(:Type) OPTIONAL MATCH (package)-[dependsOn:DEPENDS_ON]->(:Package) RETURN { // (1) role : "graph", // (2) parent : artifact, // (3) nodes : collect(package), // (4) relationships: collect(dependsOn) // (5) } ---- .... <1> Instead of nodes and relations a map-like structure is returned <2> `role` determines that the map shall be interpreted as graph containing nodes and relationships <3> `parent` specifies the node that shall be rendered as folder, i.e. the container of nodes <4> `nodes` are the nodes to be included in the folder <5> `relationships` are the relationships between the nodes, they may reference nodes of other parents/folders == Configuration The Asciidoc Report plugin accepts several options that might be passed as report properties to jQAssistant: [options="header"] |=== | Property | Description | Default | asciidoc.report.directory | Specifies the directory where the HTML files will be written | jqassistant/report/asciidoc | asciidoc.report.rule.directory | Specifies the directory where the Asciidoc files are located (optional) | | asciidoc.report.file.include | A comma separated list of filter of Asciidoc files to be included (optional) | | asciidoc.report.file.exclude | A comma separated list of filter of Asciidoc files to be excluded (optional) | | asciidoc.report.plantuml.format | Specifies the output file format of the generated PlantUML-Diagrams (optional) | SVG | asciidoc.report.plantuml.rendermode | Specifies the renderer used for the generated PlantUML-Diagrams, currently supporting GraphViz and Jdot (optional) | GRAPHVIZ |=== [[feedback]] == Feedback Please report any issues https://github.com/jqassistant-contrib/jqassistant-asciidoc-report-plugin/issues[here]. == Acknowledgements The plugin could not provide its functionality without the support of the following open source projects: * https://asciidoctor.org[Asciidoctor] * https://plantuml.com/[PlantUML] * https://neo4j.org[Neo4j] * https://jqassistant.org[jQAssistant]