Getting Started Guide

[nyxcharon]

Hello, Is there a getting started guide anywhere with what's needed to get this working? If not, could you please give me a quick outline and I can try to get something together for a PR once I've figured it out

[pakoito]

Hi Bobby! Ank is in pre-release at the moment so please use at your own risk. It's currently used in the docs of Kategory, which is our canary project for it. The version there is more up-to-date than the one here: https://github.com/kategory/arrow/tree/master/ank-core

Ank can be used as a plugin or as a standalone binary. To use it as a plugin check see kategory-docs' build.gradle: https://github.com/kategory/arrow/blob/911e94700dd299f071932f31e29fc59743ce3788/kategory-docs/build.gradle We don't provide the binary but you can easily compile and call it from master: https://github.com/kategory/ank/blob/master/ank-core/src/main/kotlin/io/kategory/ank/main.kt#L7

The usage is simple: you annotate the snippets you'd like compiled with kotlin:ank. Each file gets its own scope for dependency imports and storing variables. Ank then processes each snippet individually and appends its result as a comment at the bottom of the snippet in the output file.

If you'd like a snippet to be processed but don't want to see the result, i.e. if it returns Unit, annotate it with kotlin:ank:silent.

Here's one example file: https://github.com/kategory/arrow/blob/master/kategory-docs/docs/docs/datatypes/state/README.md and how it's rendered afterwards: http://kategory.io/docs/datatypes/state/

Known issues: coroutines and generally asynchronous code are SLOW with all caps. The scripting engine can just barely cope with them and we're looking into alternatives. Secondly, beware of re-importing large dependencies multiple times as they can also hurt performance. For example, we had one script where the whole kategory package was imported in every snippet and it took 10x the time used to process it compared to w/o them.

I hope this info is enough to get you started, and please do contact us here or in our gitter (gitter.im/kategory/Lobby) if you'd like more info.

[nyxcharon]

Thanks for the swift reply! Is there any support for processing these snippets inside of a KDoc in my source code? Or is this meant solely for standalone documentation? Basically I'm trying to achieve something like Pythons Doctest or Rust Docs so I can verify examples in my KDocs match what the code actually does

[pakoito]

Sadly only markdown documents are supported at the moment. Would you like to fill in another issue requesting KDoc compilation? it is a valuable user case.

[nyxcharon]

Issue created, thanks for all the help! I'll go ahead and close this out now, everything I needed to know has been answered