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
   

   View Slide

2. @Guardiola31337
   ΛNK
   Compile time docs verification and evaluation
   for Kotlin and Java
   

   View Slide

3. @Guardiola31337
   ΛRROW
   Functional companion to Kotlin's Standard Library
   

   View Slide

4. @Guardiola31337
   Option
   https://arrow-kt.io/docs/datatypes/option/
   

   View Slide

5. @Guardiola31337
   ```kotlin:ank
   import arrow.*
   import arrow.core.*
   val someValue: Option = Some("I am wrapped in something")
   someValue
   ```
   Option
   

   View Slide

6. @Guardiola31337
   Option output
   ```kotlin
   import arrow.*
   import arrow.core.*
   val someValue: Option = Some("I am wrapped in something")
   someValue
   // Some(I am wrapped in something)
   ```
   

   View Slide

7. @Guardiola31337
   ```kotlin:ank
   val emptyValue: Option = None
   emptyValue
   ```
   Option
   

   View Slide

8. @Guardiola31337
   ```kotlin
   val emptyValue: Option = None
   emptyValue
   // None
   ```
   Option output
   

   View Slide

9. @Guardiola31337
   ```kotlin:ank:silent
   fun maybeItWillReturnSomething(flag: Boolean): Option =
   if (flag) Some("Found value") else None
   val itWillReturn = maybeItWillReturnSomething(true)
   itWillReturn
   ```
   Option
   

   View Slide

10. @Guardiola31337
    Option output
    ```kotlin
    fun maybeItWillReturnSomething(flag: Boolean): Option =
    if (flag) Some("Found value") else None
    val itWillReturn = maybeItWillReturnSomething(true)
    itWillReturn
    ```
    

    View Slide

11. @Guardiola31337
    Option supported type classes
    ```kotlin:ank:replace
    import arrow.reflect.*
    import arrow.data.*
    import arrow.core.*
    DataType(Option::class).tcMarkdownList()
    ```
    

    View Slide

12. @Guardiola31337
    Output
    

    View Slide

13. @Guardiola31337
    MonadDefer Hierarchy
    ```kotlin:ank:outFile(diagram.nomnol)
    import arrow.reflect.*
    import arrow.effects.typeclasses.*
    TypeClass(MonadDefer::class).hierarchyGraph()
    ```
    

    View Slide

14. @Guardiola31337
    Output
    

    View Slide

15. @Guardiola31337
    Java
    ```java:ank
    int n = 3 + 3;
    return n;
    ```
    

    View Slide

16. @Guardiola31337
    Java output
    ```java
    int n = 3 + 3;
    return n;
    // 6
    ```
    

    View Slide

17. @Guardiola31337
    Errors output
    

    View Slide

18. @Guardiola31337
    ./gradlew :arrow-docs:runAnk
    cd modules/docs/arrow-docs/build/site
    jekyll serve
    Demo
    

    View Slide

19. @Guardiola31337
    Setup
    buildscript {
    repositories {
    // ...
    maven { url "https://dl.bintray.com/arrow-kt/arrow-kt/" }
    }
    dependencies {
    // ...
    classpath 'io.arrow-kt:arrow-ank-gradle:'
    }
    }
    

    View Slide

20. @Guardiola31337
    Setup
    apply plugin: 'ank-gradle-plugin'
    dependencies {
    implementation 'io.arrow-kt:arrow-ank:'
    // ...
    }
    ank {
    source = file("src/main/docs")
    target = file("build/site")
    classpath = sourceSets.main.runtimeClasspath
    }
    

    View Slide

21. @Guardiola31337
    Pitfalls
    Kotlin Script Engine becomes incrementally slower
    https://youtrack.jetbrains.net/issue/KT-17463
    

    View Slide

22. @Guardiola31337
    Pitfalls
    Annotations
    kapt can’t run over Markdown
    

    View Slide

23. @Guardiola31337
    Pitfalls
    Android
    JSR implementation lacks some extra classes
    

    View Slide

24. @Guardiola31337
    Pitfalls
    Slow?
    imports
    

    View Slide

25. @Guardiola31337
    Run Λnk
    ./gradlew :module-name:runAnk
    

    View Slide

26. @Guardiola31337
    Publish Docs
    buildscript {
    repositories {
    jcenter()
    }
    dependencies {
    classpath 'org.ajoberstar:gradle-git-publish:'
    }
    }
    apply plugin: 'org.ajoberstar.git-publish'
    

    View Slide

27. @Guardiola31337
    Publish Docs
    gitPublish {
    repoUri = 'git@github.com:/.git'
    branch = 'gh-pages'
    contents {
    from 'build/site'
    }
    commitMessage = ''
    }
    ./gradlew :module-name:gitPublishPush
    

    View Slide

28. @Guardiola31337
    What’s cooking?
    Dokka + Kotlin Playground
    https://arrow-kt.github.io/arrow-playground/
    

    View Slide

29. @Guardiola31337
    What’s cooking?
    Android support
    https://github.com/APISENSE/rhino-android?
    

    View Slide

30. @Guardiola31337
    What’s cooking?
    New modifiers
    ```kotlin:ank:compile```
    https://github.com/arrow-kt/arrow/pull/491
    

    View Slide

31. @Guardiola31337
    What’s cooking?
    Clean up resources when run fails
    

    View Slide

32. @Guardiola31337
    What’s cooking?
    Automate all the things!
    

    View Slide

33. @Guardiola31337
    KEEP-87
    https://github.com/Kotlin/KEEP/pull/87
    

    View Slide

34. @Guardiola31337
    Contributions welcome!
    Gitter gitter.im/arrow-kt
    Kotlinlang Slack #arrow channel
    

    View Slide

35. @Guardiola31337
    @Guardiola31337
    Thanks!
    Questions?
    

    View Slide