How to show Groovy and Kotlin DSL samples side-by-side

Calendar
Eric Wendelin
General

Table of Contents

Introduction

Gradle build script samples now have Kotlin DSL snippets alongside the Groovy snippets in Gradle 5.0 docs and many Gradle guides.

We want you to be able to show both DSLs in your READMEs and web-based documentation, so this post shows ways you can display examples in multiple languages on GitHub and on your websites.

Groovy and Kotlin DSL samples on GitHub #

It’s hard to find OSS projects that don’t have a README.md or README.adoc. Though there aren’t many ways to make these README pages interactive, we can use the <details> and <summary> HTML elements within Markdown or Asciidoc achieve a bit of interactivity yet avoid the verbosity of having multiple subsequent samples in view.

Use these code snippets to show multi-language snippets on GitHub.

<details open>
<summary>Groovy</summary>

```groovy
logging.captureStandardOutput LogLevel.INFO
println 'A message which is logged at INFO level'
```

</details>
<details>
<summary>Kotlin</summary>

```kotlin
logging.captureStandardOutput(LogLevel.INFO)
println("A message which is logged at INFO level")
```

</details>

++++
<details open>
<summary>Groovy</summary>
++++

[source,groovy]
----
logging.captureStandardOutput LogLevel.INFO
println 'A message which is logged at INFO level'
----

++++
</details>
++++

++++
<details>
<summary>Kotlin</summary>
++++

[source,kotlin]
----
logging.captureStandardOutput(LogLevel.INFO)
println("A message which is logged at INFO level")
----

++++
</details>
++++

Here it is in action:

Note that this won’t work for jekyll or static websites, so there we have to write a bit of code.

Groovy and Kotlin DSL samples on the web #

With a bit of CSS and JavaScript, you can make a nice little language selector UI that remembers user selections. The combination of this vanilla CSS, HTML, and JavaScript creates what you see at the top of the post.

A little bit about what the code does:

  • First, the JS initializes the preferred language, getting and storing in window.localStorage so that user preferences are saved.
  • Next, it collapses all siblings that have class=multi-language-sample and generates tabs for each sample container element.
  • Finally, when a tab is clicked the JavaScript will measure and scroll the window so that the content doesn’t “jump” in the case where snippets are vastly longer or shorter — not bad, eh?

The CSS is responsible for adds a nice Groovy or Kotlin logo to the appropriate tab, which is greyed out if the tab isn’t active.

Bonus: you can add class="multi-language-text lang-foo" to have any content be displayed only for the selected language.

I tested the code to be working in IE10+, but please let us know if there are bugs. I mean it’s not as fancy as the Google Cloud Storage docs, but I couldn’t find any good libraries to do this.

Conclusion #

These are a couple ideas you can use to show samples for multiple languages in your GitHub READMEs or on your sites. I hope you find these useful for your projects. Your other ideas and contributions are welcomed.

Discuss

Related Posts