Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Manual documentation is dead. Long live automated documentation!

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!

Pablo Guardiola

November 20, 2018
Tweet

More Decks by Pablo Guardiola

Other Decks in Programming

Transcript

  1. @Guardiola31337
    @Guardiola31337
    Manual documentation is dead.
    Long live automated
    documentation!
    Automated documentation with ΛNK
    Pablo Guardiola

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  12. @Guardiola31337
    Output

    View full-size slide

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

    View full-size slide

  14. @Guardiola31337
    Output

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  17. @Guardiola31337
    Errors output

    View full-size slide

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

    View full-size 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 full-size 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  24. @Guardiola31337
    Pitfalls
    Slow?
    imports

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  35. @Guardiola31337
    @Guardiola31337
    Thanks!
    Questions?

    View full-size slide