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

Manual documentation is dead. Long live automat...

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 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) ```
  2. @Guardiola31337 ```kotlin:ank:silent fun maybeItWillReturnSomething(flag: Boolean): Option<String> = if (flag) Some("Found

    value") else None val itWillReturn = maybeItWillReturnSomething(true) itWillReturn ``` Option
  3. @Guardiola31337 Option output ```kotlin fun maybeItWillReturnSomething(flag: Boolean): Option<String> = if

    (flag) Some("Found value") else None val itWillReturn = maybeItWillReturnSomething(true) itWillReturn ```
  4. @Guardiola31337 Setup buildscript { repositories { // ... maven {

    url "https://dl.bintray.com/arrow-kt/arrow-kt/" } } dependencies { // ... classpath 'io.arrow-kt:arrow-ank-gradle:<version>' } }
  5. @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 }
  6. @Guardiola31337 Publish Docs buildscript { repositories { jcenter() } dependencies

    { classpath 'org.ajoberstar:gradle-git-publish:<version>' } } apply plugin: 'org.ajoberstar.git-publish'
  7. @Guardiola31337 Publish Docs gitPublish { repoUri = '[email protected]:<organization>/<repo>.git' branch =

    'gh-pages' contents { from 'build/site' } commitMessage = '<commit-message>' } ./gradlew :module-name:gitPublishPush