AsciiDoc code snippets in documentation

[Michael1993]

Demonstrated in #334, we can use a neat built-in feature of AsciiDoc to include live code examples in our .adoc documentation.

The proper way to utilize this feature warrants a discussion.

[Bukama]

To copy my concerns from the draft into the discussion:

• How do you limit to (about) 60 chars per line? (see Limit line length to max 60 chars in site documentation code snippets #317 / Limit docs code snippets line length to max 60 chars (#317 / #318) #318)
• I'm not sure if this is helpfull. We often make comments in the documentation example, but not in the test cases

[Michael1993]

• How do you limit to (about) 60 chars per line?

We could use Java::Geci to format code snippets before they are inserted into the documentation. Maybe we can tell spotless to consider snippets as special cases. Maybe AsciiDoc supports reformatting? I'll look into our options and get back to you on that.

• I'm not sure if this is helpful. We often make comments in the documentation example but not in the test cases.

Yes, this is certainly a drawback. Some ideas about what we could do to counteract this problem:

• We could put the comments in the actual tests so they get copied with the snippet
• We could put the content of the comments around the snippet (e.g.: instead of saying "here we call this because", we write after the test "notice how there we called X. We did this because...")

We might decide that the fruit ain't worth the squeeze, but we won't know for sure unless we try squeezing first.

[Bukama]

@Michael1993 Could you summarize your yesterdays question and the answer to it please.

[Michael1993]

The question was: "How should we proceed with this, without polluting our tests with 'noisy demo tests'?". The answer is basically what Nicolai wrote on the PR.

@nipafx wrote on Sep 29:

I really like this approach to showing code snippets because we can always be sure that they actually work. @Bukama's concerns are valid, though. Tests and code snippets have very different concerns and we should hence separate them.

I propose to create a new source set demo (as src/demo/java) and put all the demos there. They must be written as proper tests, so we can execute them during the build, but they can be written and styled according to the documentation's needs.

If possible, we could even use Spotless to limit line length to 60 chars (if we can have different configurations for different folders - I think we already had that request once).

We agreed that this was a good approach and we should play around with it in a PR. I'll go ahead when I have the time.