# Workflow

Whether you're contributing a feature/fix to Dokka itself or developing a Dokka plugin, there are 3 essential things
you need to know how to do:

1. How to build Dokka or a plugin
2. How to use/test locally built Dokka in a project
3. How to debug Dokka or a plugin in IntelliJ IDEA

We'll go over each step individually in this section.

Examples below will be specific to Gradle and [Gradle’s Kotlin DSL](https://docs.gradle.org/current/userguide/kotlin_dsl.html),
but you can apply the same principles and run/test/debug with CLI/Maven runners and build configurations if you wish.

## Build Dokka

Building Dokka is pretty straightforward, with one small caveat: when you run `./gradlew build`, it will run
integration tests as well, which might take some time and will consume a lot of RAM, so you would usually want
to exclude integration tests when building locally.

```shell
./gradlew build -x integrationTest
```

Unit tests which are run as part of `build` should not take much time, but you can also skip it with `-x test`.

### Troubleshooting build

#### API check failed for project ..

If you see a message like `API check failed for project ..` during the `build` phase, it indicates that the
[binary compatibility check](https://github.com/Kotlin/binary-compatibility-validator) has failed, meaning you've 
changed/added/removed some public API.

If the change was intentional, run `./gradlew apiDump` - it will re-generate `.api` files with signatures,
and you should be able to `build` Dokka with no errors. These updated files need to be committed as well. Maintainers
will review API changes thoroughly, so please make sure it's intentional and rational.

## Use / test locally built Dokka

Having built Dokka locally, you can publish it to `mavenLocal()`. This will allow you to test your changes in another
project as well as debug code remotely.

1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version.
   For instance, you can set it to something like `1.9.10-my-fix-SNAPSHOT`. This version will be propagated to plugins
   that reside inside Dokka's project (such as `mathjax`, `kotlin-as-java`, etc).
2. Publish it to Maven Local (`./gradlew publishToMavenLocal`). Corresponding artifacts should appear in `~/.m2`
3. In the project you want to generate documentation for or debug on, add maven local as a plugin/dependency
   repository:
```kotlin
repositories {
   mavenLocal()
}
```
4. Update your Dokka dependency to the version you've just published:
```kotlin
plugins {
    id("org.jetbrains.dokka") version "1.9.10-my-fix-SNAPSHOT"
}
```

After completing these steps, you should be able to build documentation using your own version of Dokka.

## Debugging Dokka

Dokka is essentially a Gradle plugin, so you can debug it the same way you would any other Gradle plugin. 

Below you'll find instructions on how to debug Dokka's internal logic, but you can apply the same principles if you
wish to debug a Dokka plugin.

1. Choose a project to debug on, it needs to have some code for which documentation will be generated.
   Prefer using smaller projects that reproduce the exact problem or behaviour you want
   since the less code you have, the easier it will be to understand what's going on. You can use example projects
   found in [dokka/examples/gradle](https://github.com/Kotlin/dokka/tree/master/examples/gradle), there's both simple 
   single-module and more complex multi-module / multiplatform examples.
2. For the debug project, set `org.gradle.debug` to `true` in one of the following ways:

    * In your `gradle.properties` add `org.gradle.debug=true`
    * When running Dokka tasks:<br/>`./gradlew dokkaHtml -Dorg.gradle.debug=true --no-daemon`

3. Run the desired Dokka task with `--no-daemon`. Gradle should wait until you attach with debugger before proceeding
   with the task, so no need to hurry here.
   <br/>Example: `./gradlew dokkaHtml -Dorg.gradle.debug=true --no-daemon`.

4. Open Dokka in IntelliJ IDEA, set a breakpoint and, using remote debug in IntelliJ IDEA,
   [Attach to process](https://www.jetbrains.com/help/idea/attaching-to-local-process.html#attach-to-remote)
   running on the default port 5005. You can do that either by creating a `Remote JVM Debug` Run/Debug configuration
   or by attaching to the process via `Run` -> `Attach to process`

!!! note
    The reason for `--no-daemon` is that
    [Gradle daemons](https://docs.gradle.org/current/userguide/gradle_daemon.html) continue to exist even after the task
    has completed execution, so you might hang in debug or experience issues with `port was already in use` if you try
    to run it again.
    
    If you previously ran Dokka with daemons and you are already encountering problems with it, try killing
    gradle daemons. For instance, via `pkill -f gradle.*daemon`

In case you need to debug some other part of the build - consult the official Gradle
tutorials on [Troubleshooting Builds](https://docs.gradle.org/current/userguide/troubleshooting.html).