Use AsciiDoc snippets to include code snippets in documentation

[Michael1993]

closes #335

Signed-off-by: Mihaly Verhas misi.verhas@gmail.com

I hereby agree to the terms of the JUnit Pioneer Contributor License Agreement.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities (and 0 Security Hotspots to review)
0 Code Smells

No Coverage information
0.0% Duplication

[Bukama]

• 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

[nipafx]

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).

[nipafx]

Also, @Michael1993 can you please open an issue, so we can discuss there?

[Michael1993]

I opened #335 if that's OK?

[Bukama]

Any motivation to further work on this @Michael1993?

[Michael1993]

Any motivation to further work on this @Michael1993?

Whoops, I forgot about this. I'll do some work on it in December.

[nipafx]

Looks good. The extra ceremony of creating, tagging, and referencing the source file is non-trivial, though. I think the benefits are worth it, but we could discuss whether short snippets (like, three lines or so) could be allowed in the Asciidoc or whether this is the new standard for all tests, regardless of complexity.

[Michael1993]

The branch is ready for review - however if it gets merged, there should be another PR that migrates the rest of the docs to the new 'system'.

[nipafx]

however if it gets merged, there should be another PR that migrates the rest of the docs to the new 'system'.

Can you create an issue for that?

[Michael1993]

however if it gets merged, there should be another PR that migrates the rest of the docs to the new 'system'.

Can you create an issue for that?

#595

[nipafx]

Can you extend CONTRIBUTING.md with this text (at the end of the section "Feature Documentation"):

Code blocks in these files should not be pure text.
Instead, in the `src/demo/java` source tree, create/update a `...Demo` class that is dedicated to this feature and place code snippets in `@Test`-annotated methods in `...Demo`.
Write each snippet as needed for the documentation and bracket it with tags:

Code blocks in these files should not be pure text.
Instead, in the `src/demo/java` source tree, create/update a `...Demo` class that is dedicated to this feature and place code snippets in `@Test`-annotated methods.
Write each snippet as needed for the documentation and bracket it with tags:

```java
// tagging the entire test method:

// tag::$TAG_NAME[]
@Test
@SomePioneerExtension
void simple() {
	// demonstrate extension
}
// end::$TAG_NAME[]


// tagging a few lines from the test:

@Test
void simple() {
	// tag::$TAG_NAME[]
	SomePioneerExtension ex = // ...
	// demonstrate extension
	// end::$TAG_NAME[]
	assertThat(ex). // ...
}
```

Where feasible, include or follow up with assertions that ensure correct behavior.
Thus `...Demo` classes guarantee that snippets compile and (roughly) behave as explained.

In the documentation file, include an attribute pointing at the demo source file:

```adoc
:snippetsource: ../src/demo/java/org/junitpioneer/jupiter/...Demo.java
```

To include these snippets, use a block like the following:

```adoc
[source,java,indent=0]
----
include::{snippetsource}[tag=$TAG_NAME]
----
```

Proposed commit message:

Configure build and docs to compile and test code snippets (#335 / #334)

Code snippets in the documentation files in `docs` are just text and
thus run the risk of getting outdated when APIs evolve or
implementations change their behavior. To address that, we now use
Asciidoc's capability to include tagged regions from external
files[1] that are compiled and tested by the build. These files'
primary purpose is to demonstrate features (not to test them) and so
they are placed in a new source set `src/demojava`.

[1]: https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/

Closes: #335
PR: #334