Manual documentation is dead. Long live automated documentation!

Subtitle: Automated documentation with ΛNK

When you are developing SDKs or libraries the documentation is crucial to let users easily understand what they are, why they are useful and how to use them. The problem with manually written and maintained docs is that they can become outdated quickly and typos frequently arise, so now not only you have to fix the docs, you also have to spend time resolving the confusion you've caused to your users.

In this session we will introduce the concept of Documentation as Code by using ΛNK https://github.com/arrow-kt/ank, a way of automating documentation verification alongside the source code. ΛNK is a tool written using ΛRROW https://github.com/arrow-kt/arrow that inspects code snippets in library docs for Kotlin and Java.

We will learn how the ΛNK plugin works: from having a tool that evaluates and verifies your doc snippets at compile time, to generating code documentation that is always correct and up to date. We will also show how to integrate ΛNK with your CI service and how it can be configured. Finally, we will review several successful projects that took advantage of all these features in order to create amazing documentation sites with the best documentation like http://arrow-kt.io/

By the end of the talk, you will be itching to automate your documentation, and know how to get started with ΛNK!

Transcript

1. @Guardiola31337 @Guardiola31337 Manual documentation is dead. Long live automated documentation! Automated documentation with ΛNK Pablo Guardiola
2. @Guardiola31337 ΛNK Compile time docs verification and evaluation for Kotlin and Java
3. @Guardiola31337 ΛRROW Functional companion to Kotlin's Standard Library
4. @Guardiola31337 Option https://arrow-kt.io/docs/datatypes/option/
5. @Guardiola31337 ```kotlin:ank import arrow.* import arrow.core.* val someValue: Option<String> = Some("I am wrapped in something") someValue ``` Option
6. @Guardiola31337 Option output ```kotlin import arrow.* import arrow.core.* val someValue: Option<String> = Some("I am wrapped in something") someValue // Some(I am wrapped in something) ```
7. @Guardiola31337 ```kotlin:ank val emptyValue: Option<String> = None emptyValue ``` Option
8. @Guardiola31337 ```kotlin val emptyValue: Option<String> = None emptyValue // None ``` Option output
9. @Guardiola31337 ```kotlin:ank:silent fun maybeItWillReturnSomething(flag: Boolean): Option<String> = if (flag) Some("Found value") else None val itWillReturn = maybeItWillReturnSomething(true) itWillReturn ``` Option
10. @Guardiola31337 Option output ```kotlin fun maybeItWillReturnSomething(flag: Boolean): Option<String> = if (flag) Some("Found value") else None val itWillReturn = maybeItWillReturnSomething(true) itWillReturn ```
11. @Guardiola31337 Option supported type classes ```kotlin:ank:replace import arrow.reflect.* import arrow.data.* import arrow.core.* DataType(Option::class).tcMarkdownList() ```
12. @Guardiola31337 Output
13. @Guardiola31337 MonadDefer Hierarchy ```kotlin:ank:outFile(diagram.nomnol) import arrow.reflect.* import arrow.effects.typeclasses.* TypeClass(MonadDefer::class).hierarchyGraph() ```
14. @Guardiola31337 Output
15. @Guardiola31337 Java ```java:ank int n = 3 + 3; return n; ```
16. @Guardiola31337 Java output ```java int n = 3 + 3; return n; // 6 ```
17. @Guardiola31337 Errors output
18. @Guardiola31337 ./gradlew :arrow-docs:runAnk cd modules/docs/arrow-docs/build/site jekyll serve Demo
19. @Guardiola31337 Setup buildscript { repositories { // ... maven { url "https://dl.bintray.com/arrow-kt/arrow-kt/" } } dependencies { // ... classpath 'io.arrow-kt:arrow-ank-gradle:<version>' } }
20. @Guardiola31337 Setup apply plugin: 'ank-gradle-plugin' dependencies { implementation 'io.arrow-kt:arrow-ank:<version>' // ... } ank { source = file("src/main/docs") target = file("build/site") classpath = sourceSets.main.runtimeClasspath }
21. @Guardiola31337 Pitfalls Kotlin Script Engine becomes incrementally slower https://youtrack.jetbrains.net/issue/KT-17463
22. @Guardiola31337 Pitfalls Annotations kapt can’t run over Markdown
23. @Guardiola31337 Pitfalls Android JSR implementation lacks some extra classes
24. @Guardiola31337 Pitfalls Slow? imports
25. @Guardiola31337 Run Λnk ./gradlew :module-name:runAnk
26. @Guardiola31337 Publish Docs buildscript { repositories { jcenter() } dependencies { classpath 'org.ajoberstar:gradle-git-publish:<version>' } } apply plugin: 'org.ajoberstar.git-publish'
27. @Guardiola31337 Publish Docs gitPublish { repoUri = 'git@github.com:<organization>/<repo>.git' branch = 'gh-pages' contents { from 'build/site' } commitMessage = '<commit-message>' } ./gradlew :module-name:gitPublishPush
28. @Guardiola31337 What’s cooking? Dokka + Kotlin Playground https://arrow-kt.github.io/arrow-playground/
29. @Guardiola31337 What’s cooking? Android support https://github.com/APISENSE/rhino-android?
30. @Guardiola31337 What’s cooking? New modifiers ```kotlin:ank:compile``` https://github.com/arrow-kt/arrow/pull/491
31. @Guardiola31337 What’s cooking? Clean up resources when run fails
32. @Guardiola31337 What’s cooking? Automate all the things!
33. @Guardiola31337 KEEP-87 https://github.com/Kotlin/KEEP/pull/87
34. @Guardiola31337 Contributions welcome! Gitter gitter.im/arrow-kt Kotlinlang Slack #arrow channel
35. @Guardiola31337 @Guardiola31337 Thanks! Questions?