jQAssistant AsciiDoc Report Plugin

This is the AsciiDoc report plugin for jQAssistant.

After an analysis Asciidoctor it renders the input documents that provided rules to HTML documents.

It enriches the output by the status of executed rules as well as their results as tables, embedded diagrams or external links (e.g. CSV).

Furthermore, it provides include::[] directives for embedding the results of imported rules and summary tables.

For more information on jQAssistant see https://jqassistant.org.

Using the jqassistant-asciidoc-report-plugin

NOTE

Starting from jqassistant-asciidoc-report-plugin v2.0.0, the AsciiDoc-Report-Plugin resides under jqassistant-plugin. Therefore, not only the repository location changed but also group id and artifact id were adapted from com.buschmais.jqassistant.plugin:asciidoc-report to org.jqassistant.plugin:jqassistant-asciidoc-report-plugin.

NOTE

From jQAssistant v2.0.0 onwards, it is not part of the core distribution anymore and a manual configuration as shown below is required.

.jqassistant.yml

jqassistant:
  plugins:
    - group-id: org.jqassistant.plugin (1)
      artifact-id: jqassistant-asciidoc-report-plugin
      version: ${jqassistant.asciidoc-report-plugin.version}

1. Dependency to the AsciiDoc Report plugin

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 rules blocks are identified and replaced by their status and results appended. Furthermore, include::[] directives are provided for embedding a summary about executed and imported rules.

By default, all rule files with the name index.adoc will be selected for rendering. The report property asciidoc.report.file.include may be used to explicitly select files. Files may be located in the rule directory of a project (e.g. jqassistant/, provided by plugins or in the directory specified by asciidoc.report.rule.directory

jQA Include Directives

The report may be enhanced by jQA include directives:

jQA:Summary[concepts="…​",importedConcepts="…​",constraints="…​",importedConstraints="…​"]

Includes two summary tables containing executed rules, their description, status and severity. The filter attributes are optional, if none is given all results are included. concepts and constraints refer to rules that are defined in the rendered AsciiDoc document(s). importedConcepts and importedConstraints refer to rules that are imported from plugins.

jQA:Rules[concepts="…​",constraints="…​"]

Embeds imported rules and their results identified by the specified filters. Both filter attributes are optional but at least one must be specified.

jQA:ImportedRules[]

Deprecated Renders descriptions for all imported rules which have been executed but which are not part of the document itself (i.e. provided by plugins).

Tip	Filter attributes are comma separated lists of id patterns and may contain wildcards, e.g. "layer:*, spring-*:*".

jqassistant/index.adoc

= My Project

This document describes architectural and design rules for My Project.

== Summary

include::jQA:Summary[]

[[default]]
[role=group,includesGroups="..."]
== Project Specific Concepts & Constraints

...
project specific rules
...

== Common Spring Concepts & Constraints

include::jQA:Rules[concepts="spring*:*",constraints="spring*:*"]

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)

Distributing Of AsciiDoc Files In Plugins

AsciiDoc files may be distributed as part of plugins to allow sharing rules and reports between projects.

• Files must be located as classpath resources in the folder /META-INF/jqassistant-rules or sub-folders of it:

  META-INF/
    |-jqassistant-plugin.xml
    |-jqassistant-rules/
      |-my-reports/
        |-index.adoc             // the document to be rendered
        |-included-rules.adoc    // a file included by index.adoc providing additional rules
        |-included-misc.adoc     // a file included by index.adoc without additional rules

  Tip	Plugins should provide their reports in sub-folders (e.g. /META-INF/jqassistant-rules/my-reports) to avoid interferences with other plugins.

• AsciiDoc files may include AsciiDoc files located within the same plugin using relative paths:

  META-INF/jqassistant-rules/my-reports/index.adoc (i.e. rule file located with same plugin)

  == My Report
  
  include::included-rules.adoc[]
  include::included-misc.adoc[]

• AsciiDoc files outside a plugin may include AsciiDoc files provided by the plugins using absolute paths (without /META-INF/jqassistant-rules prefix):

  jqassistant/index.adoc

  == Project Rules
  
  include::/my-reports/included-rules.adoc[]
  include::/my-reports/included-misc.adoc[]

• AsciiDoc files containing rules must be registered in the plugin descriptor (note that included-misc.adoc is not registered)

  META-INF/jqassistant-plugin.xml

  <jqassistant-plugin>
      <rules>
          <resource>my-reports/index.adoc</resource>
          <resource>my-reports/included-rules.adoc</resource>
      </rules>
  </jqassistant-plugin>

• The AsciiDoc files may embed PlantUML diagrams:

  = Component Diagram
  
  [plantuml]
  .Building Block Diagram
  ----
  @startuml
  component "Component 1" as c1
  component "Component 2" as c2
  
  c1 --> c2 : Depends On
  @enduml
  ----

  Note	Embedding images or other resources into plugins that can be referenced by AsciiDoc files is currently not supported.

Changelog

2.0.0

• Removed Plug-In from the jQAssistant Core Distribution to jqassistant-plugin — Group and Artifact Id changed to org.jqassistant.plugin:jqassistant-asciidoc-report-plugin — Migrated Asciidoc Rule Parser from jQAssistant Core distribution to this plugin

• Extracted PlantUML reports to a separate PlantUML report plugin

1.12.2

• Fixed a problem where Asciidoc reports provided by plugins could not be rendered if the plugins were loaded from .jqassistant.yml configurations

1.12.1

• Added sorting of rules included by jQA:Rules (alphabetically by rule id)

• Added rule id to hover of rule result

• Fixed escaping of node and relationship labels in component diagrams

1.12.0

• Support the status WARNING in the summary table and rule results

• Added support for rendering PlantUML using the Eclipse Layout Kernel (Elk)

• JDOT was replaced by Smetana for rendering the PlantUML diagram when no local GraphViz installation is used.

• Delayed initialization of PlantUML to avoid unnecessary messages if GraphViz is not installed

• Removed deprecation of asciidoc.report.rule.directory

1.11.0

• Added support for rendering AsciiDoc files as reports which are provided by plugins and contain rules.

• Deprecated the report property asciidoc.report.rule.directory, it will be removed in future versions.

1.9.0

• The PlantUML diagram plugin now automatically selects GraphViz (prefered) or JDOT for rendering if not explicitly configured

1.8.0

• Include AsciiDoc Report plugin into jQAssistant main project. Note that for upgrading to 1.8 any existing dependency to the AsciiDoc Report plugin from the contrib area must be removed

• Renamed properties asciidoc.report.plantuml.format & asciidoc.report.plantuml.rendermode to plantuml.report.format & plantuml.report.rendermode