Add tested, multi-lingual user guide

[bmuschko]

• Externalize source code from user guide and embed it instead
• Very basic tests for externalized source code (the infrastructure can be improved in the future)
• Shows Groovy and Kotlin DSL source example where applicable
• User can switch between Groovy and Kotlin DSL via a tabbed view (implemented as AsciidoctorJ extension)
• Clean up of existing sample source code

The testing of the source code revealed:

• Reactive stream callbacks are currently not useable from the Kotlin DSL (as they use the Closure type)
• Some of the code examples where not functional in their current form

[cdancy]

So are we trying to convert the entire project over to kotlin at this point?

[bmuschko]

@cdancy No, this is just to document that you can use the plugin from a build script that leverages the Kotlin DSL. The plugin implementation will likely always stay in Groovy. Hope this makes things more clear.

[cdancy]

It's just a big change and trying to get a grep of what's in it. Looks entirely doc related and if I didn't know any better I'd say you were attempting to write a book about this plugin :)

[bmuschko]

@cdancy No book planned really. ;-) I do it for two reasons:

• Get familiar with the Kotlin DSL and the Kotlin language. So this project is more like a test bed.
• You will see more and more Gradle users moving away from the Groovy DSL to the Kotlin DSL (with it going 1.0 final in Gradle 5.0). At least that's my prediction. It also means that those users will try to apply this plugin. If it doesn't work with the Kotlin DSL then they will complain and open issues. This PR emulates the users and demonstrates which portions of the plugin work and don't work with the Kotlin DSL.

You are right. This PR is only about documentation. We will want to change the implementation though to allow Kotlin DSL users to use the reactive streams properly. At least I couldn't find a way to make it work yet. You might want to generate the documentation for this branch just to see the effects of the change.

[cdancy]

Sounds good. @bmuschko is the "closures not working" a known issue we can work around with Kotlin? I've only been looking into the language very recently so I'm not sure if there is something analogous we can do.

[cdancy]

Actually it appears there is a solution: https://github.com/gradle/kotlin-dsl/blob/master/doc/getting-started/Closures.md

[bmuschko]

@cdancy Thanks for this pointer. I have been using this before but without any parameters. I will give it a shot. The example you posted shows how to deal with it.

[bmuschko]

@cdancy Had a look at it again. The it refers to the Map iterator and not the Closure parameter. I will have to ask on the Gradle Slack channel if there'a solution for it. The alternative is to turn it into an Action.

[cdancy]

@bmuschko found this project this morning and appears to have a fair amount of helper functions we may be able to use with kotlin/gradle interop.

https://github.com/nebula-plugins/nebula-gradle-interop

[bmuschko]

@cdancy Thanks for the pointer. It won't be necessary. Currently, working on some internal changes that will leave the existing usage from the Groovy DSL intact while at the same time demonstrating the use from the Kotlin DSL for the reactive streams. Everything else is already useable from the Kotlin DSL.

[bmuschko]

@cdancy Here it is: #678. The beauty of having tested sample code in documentation. :-) Now it pays off.