Hey everyone. I've been working on an early Kotlin...

# feed

[Damien O'Hara]

Hey everyone. I've been working on an early Kotlin Markdown DSL and file generation library for kotlin-jvm the last couple of weeks. It supports a variety of Markdown features and provides tools for keeping generated documentation in sync, is easy to use and hosted on Maven Central. This project might be worth checking out if you have an interest in documentation generation, literate programming, documentation snapshot testing or otherwise blurring the line between code and documentation.

https://github.com/mfwgenerics/markout

Any feedback would be hugely appreciated!

[Damien O'Hara]

I should add that this was developed alongside a sibling project that allows runtime examination of lambda + class source code using a compiler plugin. By using the two of these together, you can write docs that automatically run and verify sample code

[altavir]

Our team is working on a similar project (code name SNARK), but I did not plan to make DSL for markdown. Any DSL is heavier than the markdown itself. I was more looking into extension mechanism for markdown to allow using dynamic content inside the markdown syntax. We are using JetBrains markdown library. Sadly it is a bit bugged at the moment.

[Damien O'Hara]

Thanks for the comment Alexander. I agree re: markdown DSL being heavier than markdown. For this reason Markout allows using raw markdown for inline text e.g. p("example *paragraph*"). I would be very interested to hear more about SNARK. My previous attempt at executable documentation was based around extracting Markdown from code comments in the more traditional literate programming style. I found things became messy and I needed to add things like SHOW/HIDE directives in comments

[altavir]

I use IDEA language injection and raw strings for markdawn inside the code. It works pretty fine.

[altavir]

SNARK has several separate parts. One is parsing and transforming texts (I intend to use Markdown with extensions as a primary format). It is not ready yet.

The second one is rendering engine. The prototype is available here: https://github.com/SciProgCentre/snark. Our site (https://github.com/SciProgCentre/spc-site) is working on it.

The third part is a pipeline processor and we will be working on it more this spring.

We can discuss more in #science

[Adam S]

thanks for this - I’m curious about using it in combination with (or as a replacement!) for Kotlinx Knit

[Damien O'Hara]

I appreciate the interest Adam! Part of the reason I wrote Markout is that I wanted an alternative to Knit. Markout has apply + expect workflows similar to knit and knitCheck. These interact non-destructively with existing files and directories so you can combine Markout with Knit, migrate to it incrementally or mix handwritten files in too