Create custom rouge theme

[Bukama]

As @marcphilipp asked me to push my try for a custom asciidoc theme (see #3071 ):

What I tried first was chaning the default theme to one of the other build-in themes, e.g. colorful.
This was done easy, as you only have to change the index.adoc and add the :rouge-style: colorful tag, run the gradle task "asciidoc" and the colorful theme is applied.
It doesn't matter if you set the attribute in the documentation.gradle.kts file - set settings in this file are not picked up anyway.

I then tried to create an own theme, by starting to just take the example from the asciidoc example, and just chaning some colors to blue, to make them visual and to see that the theme is picked up. I also added the file to the copy ressources list (documentation.gradle.kts) as the guide says you have to do so.

It turns out that the file is copies to build\docs\asciidoc\resources\themes\ but it does not get picked up, even I figured out that the pure existence of the file, regardless if the new added file / theme is mentioned anyway breaks the theme usage. So even when the colorful theme is set, the guide is rendered in default theme. The name / location of the theme file or the theme doesn't change anything about this behavior.

I also tried to run Gradle with "--debug" (as described in the IntelliJ Gradle Debug docs), but no debug information were written.

Well and this whole situation is what blows my mind since hours.

What you see in the PR is that the added file breaks the theme usage. Only thing that works with the current state of this PR is the copying of the file due include("resources/themes/rogue_junit.rb") in the Gradle-file. If you comment out those and remove the theme file, you will see that the setting to colorful is used again.

[marcphilipp]

@Bukama Thanks! I got it to work. The most important bit was that asciidoctor -r is short for "require" (cf. docs) so it had to be added to the asciidoctorj config.

[Bukama]

@Bukama Thanks! I got it to work. The most important bit was that asciidoctor -r is short for "require" (cf. docs) so it had to be added to the asciidoctorj config.

hmm. And I thought it was for resources, why I tried to added them to that section (where the regular code was in the source section` 🤦‍♂️

[marcphilipp]

@Bukama We'd like to include this PR in the upcoming 5.10-M1 release. Do you have time to make the changes requested in #3071 (comment) until mid next week?

[Bukama]

Removed the dark theme, based on team decision in the linked issue and turned the draft PR into a regular PR.

Proposed commit message.

Create custom rouge theme

The rouge code formatting themes are used
by asciidoc, which is used to create the
user guide. But the default theme and all
overs, except the "bw" theme, will create
low color contrast, which can be problematic
for people with visual restrictions.

Instead of using rouge's "bw" theme a custom
theme was created to tackle these issue, because
using the "bw" theme there was no visual switch 
between regular text and code examples.

The created theme is a light themes that 
solves all contrast errors in the user guide.
However it can't fix other accessibility problems
of the user guide, like missing link textes.
Those other problems have to be fixed seperately.

relates to #3071
#PR 3267

[marcphilipp]

@Bukama Thanks for your perseverance in getting this addressed! 👍