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!

3c2bdd16c0ea8511dc254b8497a06f78?s=128

Pablo Guardiola

November 20, 2018
Tweet

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?