Custom Assciidoc templates for rules

[Tim Teulings]

Hello,

I'm the author of https://github.com/Framstag/acousticrules, using the project to work and test using JQAssistant. Goal is to not only write tests but use JQAssistant together with its Asciidoc generation facilities to get some more general architecture description (some mixture of Arc42 and ADRs, though current structure does not reflect this), by adding generated images and tables (the truth is in the code :-)).

Since for this I find the default templates (RulesConcept, RulesConstraint, Summary) for rule result "includes" a little bit too "heavy". I thus tried to replace them with custom ones:

Added in pom.xml:

<jqassistant-templates-path>
${project.basedir}/src/docs/templates
</jqassistant-templates-path>

Added src/docs/templates:

> ls  src/docs/templates
IconEnabler  NoResult  RulesConcept  RulesConstraint  Summary

See...

INFO] Template loading location set to /home/tim/projects/acousticrules/src/docs/templates. If template is not defined in this location, the extension will default to the respective default template.

...in the output of

> mvn asciidoctor::process-asciidoc

But looks like the internal default templates are still used.

What am I doing wrong?

Best wishes...

Tim

[Dirk Mahler]

Hi Tim,

I just cloned your repo and gave it a try - you're using it correctly, it's a bug in the extenion. Would you mind to create an issue on GitHub (https://github.com/jqassistant-tooling/jqassistant-asciidoctorj-extensions/issues)?

Cheers

Dirk

PS: Your project contains a nice jQA rule set ;-)

------ Originalnachricht ------

Von "'Tim Teulings' via jQAssistant" <jqass...@googlegroups.com>

An "jQAssistant" <jqass...@googlegroups.com>

Datum 10.10.2023 15:20:46

Betreff [jQAssistant] Custom Assciidoc templates for rules

--
You received this message because you are subscribed to the Google Groups "jQAssistant" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jqassistant...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/15167ead-e791-4706-8f77-cbb88a579aecn%40googlegroups.com.

[Dirk Mahler]

Hi,

a ticket has been created by Aurélien for that issue: https://github.com/jqassistant-tooling/jqassistant-asciidoctorj-extensions/issues/13 - thanks!

And there's good news from our siode: A fix has been implemented, tested and is ready to be released. Does anyone want to give it a try and provide feedback before we actually do that? It's available from the Sonatype OSS repository as 1.1.0-SNAPSHOT.

For the templates being too heavy: that's recognized - do you have more compact proposals that you would like to share?

Cheers

Dirk

------ Originalnachricht ------

Von "'Tim Teulings' via jQAssistant" <jqass...@googlegroups.com>

An "jQAssistant" <jqass...@googlegroups.com>

Datum 10.10.2023 15:20:46

Betreff [jQAssistant] Custom Assciidoc templates for rules

--

[Aurélien Mino]

Hi,

I tested the fix in the snapshot version and it works fine, thanks!

Regarding the template alternative content: my main use of jqassistant is a (very powerful) live documentation tool.

For my needs, the generated documentation will only contain concepts (with different report types), but no constraints.

For displaying the concepts, I don't need any concept id, status and severity. I just need the description and the content (result or reports).

My RulesConcept template will probably looks like this one: https://gist.github.com/murdos/3e26aeaa8adf7f186615d04f22eaa02a (I tried to replace the rule.id by the rule.description for the section title but it doesn't work currently).

Cheers,

Aurélien

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/em9f49df0c-2eab-45c7-bbaa-85ef374a42f7%405e3a7271.com.

[Dirk Mahler]

Hi Aurélien,

thanks for the feedback - we'll create a 1.0.1 release for the extension.

Regarding "rule.description" vs. "rule.id": 

I gave it a try and saw that the description is not rendered as a heading but as text instead with a leading "=", correct? 

If so, then this is related to a leading line break in the rule description, it's likely that it must be fixed in the jQA core. If you confirm then I'll create an issue for that.

Cheers

Dirk

------ Originalnachricht ------

Von "Aurélien Mino" <aureli...@gmail.com>

An jqass...@googlegroups.com

Datum 20.10.2023 21:47:23

Betreff Re: [jQAssistant] Custom Assciidoc templates for rules

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/CACXN3_jG5nEB-Rr5KTWuh8QxhBfc%3DLZCOgkkHDTB0wvjR9F3hw%40mail.gmail.com.

[Aurélien Mino]

Hi,

Nice catch! It's indeed an issue with line break. After removing line breaks in xml, it works.

In my case it was caused by a line break at the end of the description:

<description>Description xxxx

</description>

Cheers,

Aurélien

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/eme9b5b34f-a13e-45ae-aed4-d253f002b310%405e3a7271.com.

[Tim Teulings]

Hello Dirk,

I just cloned your repo and gave it a try - you're using it correctly, it's a bug in the extenion. Would you mind to create an issue on GitHub (https://github.com/jqassistant-tooling/jqassistant-asciidoctorj-extensions/issues)?

Sorry for the late answer, seems I'm missing some notification settings for google groups :-/ Thanks to Aurélien for creating the issue!

PS: Your project contains a nice jQA rule set ;-)

The idea is to use JQAssistant more for "living documentation" than "just" architecture testing. As such the current template is too heavy for me. Especially chapter marks should be defined by the surrounding document not be enforced by the template. Also, the result (value, table, graphic) should be emphasized. Positive/negative test result should be visible, but not so much put in the foreground (we have the build that breaks in this case).

I would also like to do some advertising for the actual (at little bit overengineered) application though, too :-)

The fixed has not been released as a new version? I would like to test it, too, and especially work an a better template (for me), too.

Best wishes...Tim

[Dirk Mahler]

Hi Tim & Aurélien,

I just hit the release button, 1.0.1 of the extension containing the fix should be available via Maven Central within the next hour.

Furthermore I created an issue to trim the description in XML files containing rules to avoid the broken Asciidoc rendering, see https://github.com/jQAssistant/jqa-core-framework/issues/83.

Cheers

Dirk

------ Originalnachricht ------

Von "'Tim Teulings' via jQAssistant" <jqass...@googlegroups.com>

An "jQAssistant" <jqass...@googlegroups.com>

Datum 01.11.2023 14:46:31

Betreff Re: [jQAssistant] Custom Assciidoc templates for rules

--

You received this message because you are subscribed to the Google Groups "jQAssistant" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jqassistant...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/813d6b2a-60d2-4074-9bf1-2fa612426549n%40googlegroups.com.

[Tim Teulings]

Hello everybody,

Hi Tim & Aurélien,

I just hit the release button, 1.0.1 of the extension containing the fix should be available via Maven Central within the next hour.

I was now able to make use of my own custom templates and did some initial work to make generated documentation more smooth. Thanks a lot!

Best wishes...Tim