Automated documentation deployments using Kotlin & Netlify

Introduction

In this short article, I will briefly discuss documenting Κotlin code & deploying it to Netlify. In case you've been living under the rock for the last couple of years, Netlify is the leading solution to static site deployments & services all around the JAM stack. It is built with simplicity in mind, and it has a CLI tool which means we can access it from a CD environment like Travis for more robust deployments. I'm talking about web deployments, which implies the files are HTML, CSS and JavaScript only, which again implies that the documentation we will be generating, is of this type.

What we'll be using throughout this article

  • GitHub
  • Travis CI/CD
  • Maven

Prerequisites

You will need to

  • Have a kotlin project using Maven (Other build tools are not covered but alternatives will be discussed)
  • Be familiar with KDoc
  • Install KDoc, following the documentation

Next steps

Assuming you have a barebones Maven project, let's document a simple Kotlin function according to KDoc's rules.

/**
 * The animal class
 *
 * This is the best animal class you can find!
 *
 * @property name The name of the animal
 * @property makeSound The function which contains how the animal makes a sound
 * @constructor Makes a new animal, but you need to pass the name and the makeSound function
 * @since 1.0.0
 */
class Animal {

    private var name: String? = null;
    private var makeSound: () -> Unit = fun() {}

    constructor(name: String, sound: () -> Unit) {
        this.name = name
        this.makeSound = sound
    }

}

Don't worry about the functionality of the above code, the purpose of using this function, is because it contains a lot of comments for the KDoc engine.

The KDoc engine will parse the code, extract those comments, and generate an HTML documentation for us. It would be wise to test it locally first and then deploy, but because it's the end of the world (COVID-19) we will risk & deploy straight to production.

In order to set up automated deployments, we need a tool called Travis. This tool is not free for private repositories (unless you are a student) and is pretty expensive too. I can't think of a free alternative besides GitHub Actions, so I would love your contributions at the comments down below.

Travis has a configuration file in order to work, the ".travis.yml" file. This file needs to be at the top level of your GitHub repository in order to be recognized by the Travis tool. Let's use the following configuration for Travis:

language: java

sudo: true

install:
  - mvn install -DskipTests=true -Dmaven.javadoc.skip=true -B -V --quiet

script:
  - mvn -ntp dokka:dokka

deploy:
  provider: netlify
  site: <site-id>
  auth: <auth-id>
  edge: true
  dir: docs
  prod: true

By default, when Travis sees that you have a Maven project, it will install all the necessary tools & dependencies you need. The language is set to Java because Kotlin is Java disguised and we don't want to lie to Travis, he's our friend.

Alt Text

The default Travis installation command is mvn install -DskipTests=true -Dmaven.javadoc.skip=true -B -V however, we need to add the --quiet flag because it is extremely verbose and will result in more than 400 log lines in the CD environment. If you followed the Dokka instructions properly, your pom.xml will contain the following code (except configuration).

If you are not sure which dokka.version variable to use, you should prefer the latest one, found here.

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <version>${dokka.version}</version>
    <executions>
        <execution>
            <phase>pre-site</phase>
            <goals>
                <goal>dokka</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <outputDir>docs</outputDir>
        <outputFormat>html</outputFormat>
        <sourceDirectories>
            <dir>src/main/kotlin</dir>
        </sourceDirectories>
        <skipEmptyPackages>true</skipEmptyPackages>
    </configuration>
</plugin>

The configuration above is 100% optional, however, it's good to customize things to fit exactly your needs.

In order to build the docs, you need to use the command mvn -ntp dokka:dokka and that's why it is located at the script sector of Travis's configuration file.

Now let's look at the deploy sector. We will use Netlify Drop, but first we need to get a "site" and "auth" key. Let's do that in the next chapter!

Configuring Netlify

Make a folder, write a plain HTML file (could be empty), and put it inside this folder. Now go to Netlify and drag this folder to upload it.

Alt Text

When you finish dragging the folder, Netlify will create a new website for you which will contain the website's ID.

Go to "Site Settings" and save the API ID somewhere you can easily access (e.g notepad). Now go to https://app.netlify.com/user/applications and click on "New access token". Enter a name for the app (e.g docs) and click on "Generate token". This token is the "auth-id" we mentioned earlier so copy and paste it there. The "site-id" you previously stored, is the "site-id" on the Travis file, so paste it there as well.

Final steps

Commit your changes, push them to any branch, and Travis will automatically trigger a build which will publish the docs on the specified Netlify website you created.

Notice 1: As of the 25th of April 2020, there is an issue with the documentation's styling. You can read more about this issue

here

. The issue is related to the structure of the output. To be more specific, the output is not inside just one folder so the build process is confusing. This results to the URL being "xxxxx.netlify.app/project-name/" instead of "xxxxx.netlify.app/". Technically, this is not a major issue, considering you can fix it with an NGINX configuration, but this is not covered in this article because we are using Netlify.

Notice 2: Private keys are meant to be private, it's a good idea not to store them publicly unless you absolutely need to. Consider using a proper

encryption

that Travis offers. In that way, you can stay safe from attacks. Those kinds of attacks are of high severity and can impact confidentiality in a major way.

Thanks for reading 🎉

Let me know what you think by commenting below. This article uses Maven, however, you can do the same with Gradle and other build tools that KDoc supports. It's up to you to pick a tool that works for you best. I am not familiar with Gradle, so I can't say anything about it for now.