I want to create a documentation site for a Kotlin...

# getting-started

[Donny]

I want to create a documentation site for a Kotlin library's (https://github.com/fabmax/kool) JS platform output. I'm going to be using Docusaurus (a static site generator). I want to have documentation that shows the code running (it will be code that shows WebGL graphics so its appropriate for web output). This code will have an associated code block that shows the code in Kotlin and the code in Javascript (using built Javascript library). I want to have the code implementation actually working in both Kotlin/JS and Javascript. Then I want to have that code embedded in Docusaurus.

By the Kotlin/JS version and Javascript version I mean one version of the demo is written in Kotlin and compiled and the other is written in Javascript using the compiled Javascript library. It's an important distinction.

My question is how to approach this:

I will have to have a single platform (Javascript) Kotlin project that imports this library, and whose output is a series of demo usages of this library. Then I can either:

a) have a completely separate repo that I use with docusaurus. I import the built kotlin js library manually. The advantages of this approach are that I'm keeping the Kotlin and Javascript projects separate and reducing the complexity. Incremental building is difficult because I have to build one project then build the other. However, I could just do the Javascript version of the demos first with docusaurus and then go back in later and do all the Kotlin versions of the code.

b) I include the docusaurus project in the Kotlin project and create a gradle task that builds it when I like. Is this possible? Has anyone done anything like this? The advantages of this are that the build process is simplified and I have a single source of truth. In an ideal world, I could somehow include the output of the Kotlin/JS demos in docusaurus.

[Donny]

I realize this is less of a Kotlin question and more of an Intellij Idea question of how to organize a project.

[Adam S]

are you asking about how to test the examples in the documentation, to make sure they’re up to date? Or how to run the examples in browser, so visitors can run and edit them? (for example, you can run and edit the example snippets beneath each function https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/chunked.html)

[Adam S]

for the first option, there’s a few ways of testing docs, which can be broadly divided into two approaches: code first or docs first

Code first, and generate snippets from the code

• for mkdocs https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
• https://github.com/mfwgenerics/markout, which is a DSL for writing docs with Kotlin
• https://github.com/glureau/grip
Docs first, extract snippets, and test them

• https://github.com/Kotlin/kotlinx-knit/ My preference - but not by much! It’s nice writing docs all in one page, and the generated docs are great. But it’s a bit awkward and would be helped with more features and an easier interface. Most well used by Kotlinx Serialization