Add tests to verify the documentation examples are valid

At the moment one of the examples in the docs doesn’t compile

https://github.com/krzema12/github-actions-kotlin-dsl/blob/32576f647c533f087eed07a93564a56f418d78cd/docs/user-guide/getting_started.md?plain=1#L35-L45

job(name = "test_job", runsOn = UbuntuLatest) {
// Error: No value passed for parameter 'id'

I’d like to use Knit to solve the problem of the docs getting out of sync.

Recently I’ve been using Knit to verify that the documentation examples are correct. It provides a simple way of testing any source code that’s in the docs. The tests are then run as part of the usual test suite. If the API changes, then the tests in the docs fail.

A good example project that uses Knit is Kotlinx Serialization: https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/basic-serialization.md#json-encoding

I’ll make a quite demo PR (I’ll base it off the ‘update Gradle’ PR, but it’s not necessary - either can be done independently )

[jmfayard]

@krzema12 mkdocs has a list of plugins here https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins

https://github.com/rnorth/mkdocs-codeinclude-plugin seems to be what you are looking for

<rant> It’s one of the things that everyone needs but is not in markdown. Like for table of contents. So everyone is reinventing the wheel in an incompatible way. Asciidoc does this by default https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/ </rant>

[aSemy]

I’ve found the issue with running the scripts, it’s something to do with kotlinx-knit https://github.com/Kotlin/kotlinx-knit/issues/41