jqassistant-asciidoctor-extension

The jqassistant-asciidoctor-extension is an asciidoctor extension that offers a convenient way of creating a jQAssistant report inside the asciidoctor pipeline. The plugin is using the asciidoctor extension api to hook into the asciidoctor pipeline.

You can use it to convert your jqassistant-report.xml (jQAssistant generates this for you) directly to html, pdf, ePub and others, as long as there’s an Asciidoctor converter for it.

Using the jqassistant-asciidoctor-extension

As an example of how to use the plugin, you can take a look at the following maven plugin configuration for the asciidoctor-maven-plugin.

<!-- Define the following inside the build part of your pom.xml -->

<plugins>
    <plugin>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>2.2.2</version>
        <configuration>
            <attributes>
                <jqassistant-report-path>
                    ${project.build.directory}/jqassistant/jqassistant-report.xml (1)
                </jqassistant-report-path>
                <jqassistant-templates-path>
                    your-custom-template-jar-or-folder-name (2)
                </jqassistant-templates-path>
                <imagesDir>
                    your-desired-folder-to-store-pictures-inside-your-output-directory (3)
                </imagesDir>
            </attributes>
        </configuration>
        <executions>
            <execution>
                <id>output-html</id>
                <phase>verify</phase>
                <goals>
                    <goal>process-asciidoc</goal>
                </goals>
            </execution>
        </executions>
        <dependencies>
            <dependency>
                <groupId>org.jqassistant.tooling.asciidoctorj</groupId>
                <artifactId>jqassistant-asciidoctorj-extensions</artifactId>
                <version>1.0.0</version> (4)
            </dependency>
        </dependencies>
    </plugin>
</plugins>

1. place the path to your jqassistant-report.xml here. Check Finding your jqassistant-report.xml for information.

2. OPTIONAL: If not declared, the extension will use the default templates. If you want to use your templates, place the name of your custom templates location here. For more information refer to section Using your own template.

3. OPTIONAL: If you add this option, the extension will copy all pictures (f.e. diagrams) generated by jQAssistant into the defined folder. The folder will be created by asciidoctor relative to the generated docs folder.

4. place your desired version of the extension here. Check maven repository for the newest version.

Create your report

In general, there are two possible macros (called includes) you can use with the jqassistant-asciidoctor-extension.

1. include::jQAssistant:Summary[] will give you a summary table of all constraints and concepts with their id, description, severity and status. They’re sorted by Status and id name.

2. include::jQAssistant:Rules[] will give you a detailed list of all constraints and concepts with additional information like result tables or graphs

For both of them, you have the option to assign two additional attributes:

• concepts

• constraints

You can assign an id or id wildcard to either of them. In this case, you get back some specific jQAssisstant concepts and constraints. This could look like this:

• include::jQAssistant:Summary[concepts="jQA:my:specific:concept-id"] would result in a summary table that only contains the concept with the name jQA:my:specific:concept-id (if it exists). Constraints are not rendered in this case.

• include::jQAssistant:Summary[concepts="jQA:my:specific:concept-id", constraints="*"] would result in a summary table containing the concept with the name jQA:my:specific:concept-id. Also, all constraints will be displayed.

• include::jQAssistant:Rules[constraints="jQA:a*", concepts="jQA:my:specific:concept-id"] would result in a list containing all constraints with their details that start with "jQA:a". Also, it will contain exactly one concept (if it exists) with the id "jQA:my:specific:concept-id" (this concept will also be displayed with its details).

Note	The described behavior only applies if you use the default templates. If you assign custom templates, these includes may display different contents.

Note	Normally include::…​ 's are used to reference and display other files inside the adoc file they’re written in. In our case, tho these include::…​ 's are replaced by the jqassistant-asciidoctor-extension.

Note

The standard behaviour of the default templates is to render Rule-Ids in the include::jQAssistant:Rules[] with level 0 headings (adoc notation: =). If you want to change that, you may use the leveloffset attribute. F.e. include::jQAssistant:Rules[leveloffset=+1]: This would yield an output with all Rule-Ids having a level 1 heading instead of level 0 (adoc notation: = → ==).

Finding your jqassistant-report.xml

Normally you can refer to your jqassistant-report.xml via ${project.build.directory}/jqassistant/jqassistant-report.xml. You can check the exact location by searching for jqassistant-report.xml in your jQA output directory (this xml is created by jQA at runtime).

Using your own template

This extension uses freemarker templates to personalize your report. The basic idea behind a freemarker template is, to fill a template with the data contained in a root element. Normally there are default templates already provided with this extension. If you want to declare your own templates, put the jar or folder with your freemarker templates inside your resource folder. All templates that are not defined will use the default templates. Add the name of the jar or folder to your configuration as described in Using the jqassistant-asciidoctor-extension.

Fill your template with data from the root element

For this part, you need to have a basic understanding of how to write a freemarker template and how to reference the data from your root element. For information on how to write your freemarker template please refer to the Freemarker template author’s guide.

There are five templates you can create for the extension to use.

• IconEnabler This template is used to assign your own document attributes for the asciidoctor processing. Its content is placed at the beginning of each adoc. This happens before the processing of your includes. See IconEnabler for the structure of the default IconEnabler.

• Summary This template is used for the include::jQAssistant:Summary[] call.

• RulesConcept This template is used for the concepts part of the include::jQAssistant:Rules[] call.

• RulesConstraint This template is used for the constraints part of the include::jQAssistant:Rules[] call.

• NoResult This template is used in case of no matching concepts or constraints (both in include::jQAssistant:Summary[] and include::jQAssistant:Rules[]). It’s main purpose is to signalize a wrong id filter.

Note	For templates 2-5 the RuleRoot object is used to enrich the template with information. See RuleRoot usage for more information.

IconEnabler

Default "IconEnabler" template

:caution-caption: 🔥 ERROR
:tip-caption: ✅ SUCCESS
:warning-caption: ⚠ WARNING
:note-caption: ⚡ SKIPPED

One possibility here is to add the :icons: attribute and set it to font. This allows you to use icons in your other templates. Another possibility is to remove all the content in the IconEnabler. This allows you to use the standard asciidoctor icons for the admonition blocks.

RuleRoot usage

The jqassistant-asciidoctor-extension provides a root element, that is then combined with your freemarker template to create the finished report. You can take a look at the following example template to understand the data structure provided by the extension.

Default "RulesConcept" template

<#list concepts as rule>  (1)
[#jqassistant_${rule.id}]
= ${rule.id} (2)
****
<#if rule.status == "SUCCESS"> (2)
TIP: ${rule.description} + (2)
Status: [green]#${rule.status}#, Severity: ${rule.severity} (2)
<#elseif rule.status == "WARNING">
WARNING: ${rule.description} +
Status: [yellow]#${rule.status}#, Severity: ${rule.severity}
<#elseif rule.status == "FAILURE">
CAUTION: ${rule.description} +
Status: [red]#${rule.status}#, Severity: ${rule.severity}
<#else>
NOTE: ${rule.description} +
Status: [grey]#${rule.status}#, Severity: ${rule.severity}
</#if>

<#if rule.hasReports> (3)
<#list rule.reports.links as labeledLink> (5)
link:${labeledLink.link}[${labeledLink.label}] (6)

</#list>
<#list rule.reports.images as labeledImage> (5)
[caption="", title=${labeledImage.label}] (6)
image::${labeledImage.link}[${labeledImage.label}]

</#list>
<#elseif rule.hasResult> (4)
|===
<#list rule.resultColumnKeys as key>|${key} </#list> (7)
<#list rule.resultRows as row> (8)
<#list row as cell> (9)
|${cell}
</#list>
</#list>
|===
</#if>
****
</#list>

1. You can refer to your returned constraints and concepts via the constraints or concepts identifiers. Specifically, each of them is internally handled as a sorted set (primarily sorted by status from failure to warning to success to skipped and secondarily by id in alphabetical order). In case the NoResult template is used, the RuleRoot object holds an empty list of concepts and constraints.

2. For each concept and constraint (here represented by rule) you can refer to their id, description, status or severity by using rule.id, rule.description, rule.status, and rule.severity.

3. Via rule.hasReports you can check whether the corresponding concept or constraint generated any pictures (e.g. graphs) or external files (e.g. CSV’s) to display.

4. Via rule.hasResult you can check whether the corresponding concept or constraint generated a result table to display. This table may contain things like dependencies or other related information.

5. rule.reports gives you access to the list of external files (via rule.reports.links) and to a list of generated images (via rule.reports.images)

6. Both external files and images use the same internal type (namely URLWithLabel) to give access to the location (labeledLink.link or labeledImage.link depending on the naming in the <#list> block) and to the label (labeledLink.label or labeledImage.label). (Consider using hasReports beforehand. See (5))

7. You can access the header of your table using the resultColumnKeys identifier. This gives you a list of the column names for the table. (Consider using hasResult beforehand. See (4))

8. You can access a list of all rows via resultRows

9. You can access each individual cell (containing a string value) of one row via <#list row as cell> (each row itself is a list of Strings). In our example we listed each row via <#list rule.resultRows as row> and for each listed their cells (strings) via <#list row as cell>.

Default "Summary" template:

[opts="header"]
|===
|Id |Description |Severity |Status
<#list constraints as constraint>
|<<jqassistant_${constraint.id}>> |${constraint.description} |${constraint.severity}
|[<#if constraint.status == "SUCCESS">green<#elseif constraint.status == "FAILURE">red<#elseif constraint.status == "WARNING">yellow<#else>grey</#if>]#${constraint.status}#
</#list>
<#list concepts as concept>
|<<jqassistant_${concept.id}>> |${concept.description} |${concept.severity}
|[<#if concept.status == "SUCCESS">green<#elseif concept.status == "FAILURE">red<#elseif concept.status == "WARNING">yellow<#else>grey</#if>]#${concept.status}#
</#list>
|===

Changelog

1.0.1

• fixed an issue where custom templates have not been loaded from the configured directory

1.0.0

• Initial release