/jqassistant-asciidoc-report-plugin

jQAssistant report plugin for rendering Asciidoc rule documents to HTML including results as tables and diagrams.

Primary LanguageJavaGNU General Public License v3.0GPL-3.0

jQAssistant Asciidoc Report Plugin

Table of Contents

This project provides a jQAssistant report plugin for rendering Asciidoc documents containing rules and embedding their results.

How It Works

The plugin records the results of executed rules (i.e. concepts and constraints). At the end of the analysis phase 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 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

  • Java 8 or higher

  • Maven 3.2.5 or higher

  • jQAssistant 1.6.0

Setup

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

pom.xml
<build>
    <plugins>
        <plugin>
            <groupId>com.buschmais.jqassistant</groupId>
            <artifactId>jqassistant-maven-plugin</artifactId>
            <version>1.6.0</version>
            <executions>
                <execution>
                    <id>default-cli</id>
                    <goals>
                        <goal>scan</goal>
                        <goal>analyze</goal>
                    </goals>
                    <configuration>
                        <!--
                        <reportProperties>
                            <asciidoc.report.rule.directory>${session.topLevelProject.basedir}/jqassistant</asciidoc.report.rule.directory> <!--(1)-->
                            <asciidoc.report.file.include>index.adoc</asciidoc.report.file.include>                                         <!--(2)-->
                        </reportProperties>
                        -->
                    </configuration>
                </execution>
            </executions>
            <dependencies>
                <dependency>                                                                                                                <!--(3)-->
                    <groupId>org.jqassistant.contrib.plugin</groupId>
                    <artifactId>jqassistant-asciidoc-report-plugin</artifactId>
                    <version>1.6.0</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

  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 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 PlantUML which itself relies on 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:

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

Please report any issues here.

Acknowledgements

The plugin could not provide its functionality without the support of the following open source projects: