How Can I publish the Docs to Github pages after generating it via Dokka (Kotlin)?

Question

I've successfully generated the Kotlin doc using Dokka for Android projects. Now how can I publish to Github Pages.

Answer 1

Use one of the Github Pages actions.

On one of my projects I've used JamesIves/github-pages-deploy-action. Here's an example:

name: Docs
on:
  push:
    branches: [master]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          persist-credentials: false
      - name: Set up JDK
        uses: actions/setup-java@v1
        with:
          java-version: 11
      - name: Build documentation
        run: ./gradlew asciidoctor
      - name: Publish documentation
        uses: JamesIves/github-pages-deploy-action@releases/v3
        with:
          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
          BRANCH: gh-pages
          FOLDER: build/docs

You'll need to adapt the build step to your build process and tweak the path where the docs are generated.

You'll also need to define the ACCESS_TOKEN secret (Settings -> Secrets in your repository). The token can be generate in your profile Settings -> Developer Settings -> Personal access tokens.

There's more actions to choose from , i.e. https://github.com/marketplace/actions/github-pages-action, so do your research and choose the one that suits you best.

Answer 2

Add Dokka to project build.gradle.kts

plugins {
    id("org.jetbrains.dokka") version "1.9.10"
}

tasks{
    register<Jar>("dokkaJar") {
        from(dokkaHtml)
        dependsOn(dokkaHtml)
        archiveClassifier.set("javadoc")
    }
}

Add Github Action

name: Docs

on:
  push:
    branches: [ main ]

 ## Delete below when merged to main!
 ## Added such that one can test pages deployment on branch before merging
  pull_request:
    branches: [ main ] 

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: 21
          distribution: 'adopt'

      - name: Build documentation
        run: ./gradlew dokkaHtml

      - name: Publish documentation
        uses: JamesIves/github-pages-deploy-action@releases/v4
        with:
          BRANCH: gh-pages
          FOLDER: build/dokka/html

Run it once for it to create your new gh-pages git branch.

Enable Github Pages for your repository

• Project -> Settings -> Pages tab
• Source: Deploy from a branch
• Branch: gh-pages

---

To summarize, you may use this Github Action: https://github.com/JamesIves/github-pages-deploy-action

To use it you need to create your own Github Action that:

• Builds the Dokka website: ./gradlew dokkaHtml
• Invokes the JamesIves Github Action
  • Passing it where the newly built website can be found: build/dokka/html/
  • Passing it a git branch name to where it can copy the site onto gh-pages

Then setup the repo's Github Pages to point to the branch gh-pages.

Every time you run your Docs Github Action it'll generate a Dokka site, copy it to gh-pages, which Github Pages points to publish to https://{userid}.github.io/{repo_name}

Check out my example here: https://github.com/seljabali/java-time-fun/