Dokka

Conocimientos previos

Dokka genera documentación de tu código Kotlin/Java.

Según el formato de salida (HTML, Javadoc, Markdown) que deseas, los plugins a declarar cambian.

🔧 Repositorio

Instalación básica

• En build.gradle.kts (Proyecto raíz)

  build.gradle.kts (Proyecto raíz)

  plugins {
  id("org.jetbrains.dokka") version "2.0.0"
  }
  
  buildscript {
  dependencies {
      classpath("org.jetbrains.dokka:dokka-base:2.0.0")
  }
  }
  

• En build.gradle.kts (Módulo :app)

  build.gradle.kts (Módulo :app)

  plugins {
  id("org.jetbrains.dokka") version "2.0.0"
  }
  
  dependencies {
  dokkaPlugin("org.jetbrains.dokka:android-documentation-plugin:2.0.0")
  }
  

• Migración a Dokka V2

  Agrega en gradle.properties:

  gradle.properties

  # Habilitar Dokka V2
  org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
  org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true
  
  # Mejorar rendimiento en compilación
  org.gradle.caching=true
  org.gradle.parallel=true
  

• Generar documentación

  Ejecuta en terminal en el root del proyecto:

  bush

  ./gradlew dokkaGenerate
  

  Formato HTML: Podrás ver un enlace local para revisar la documentación.

Por defecto, se genera en: ./app/build/dokka (a menos que configures otro directorio).
• Modificar directorio de salida

  Si quieres que la documentación no se elimine al limpiar (./gradlew clean), define un directorio persistente. En build.gradle.kts (:app):

  Gradle

  dokka {
  dokkaPublications.html {
      outputDirectory.set(rootDir.resolve("docs/dokka"))
  }
  }
  

• Configurar estilos y personalización

  Para personalizar estilos, logos y comportamiento, usa la siguiente configuración en build.gradle.kts (:app):

  Gradle

  dokka {
  moduleName.set("Mi Proyecto Android")
  
  dokkaPublications.html {
      suppressInheritedMembers.set(true)
      failOnWarning.set(true)
      outputDirectory.set(rootDir.resolve("docs/dokka"))
  }
  
  dokkaSourceSets.configureEach {
      includes.from("Module.md")
  
      sourceLink {
          localDirectory.set(file("src/main/java/"))
          remoteUrl.set(URL("https://github.com/miusuario/miproyecto/tree/main/app/src/main/java"))
          remoteLineSuffix.set("#L")
      }
  
      documentedVisibilities.set(setOf(VisibilityModifier.Public, VisibilityModifier.Private))
  }
  
  pluginsConfiguration.html {
      footerMessage.set("2025 © EMMA by Arkana Apps")
      customAssets.from("../docs/assets/emma-logo.png")
      customStyleSheets.from(
          "../docs/assets/style.css",
          "../docs/assets/logo-styles.css"
      )
  }
  }
  
  

✅ moduleName: Nombre visible en la documentación.

✅ suppressInheritedMembers: Oculta miembros heredados.

✅ failOnWarning: Falla si hay warnings (útil en CI/CD).

✅ sourceLink: Enlaza a tu GitHub para ir directo al código.

✅ footerMessage y customAssets: Personaliza logos, CSS, y pie de página.

Automatización de despliegue

objetivo principal de estos pasos es generar y desplegar documentación con Dokka (para proyectos Kotlin o Android) en GitHub Pages, cada vez que se haga un push a la rama main.

• Desencadenador (on)

  Este workflow se ejecuta automáticamente cuando se hace un push a la rama main.

  Yaml

  on:
  push:
  branches: [ main ]
  
  

• Permisos

  Dar permisos

  Yaml

  permissions:
  contents: write
  pages: write
  id-token: write
  

• Preparación del entorno

  Se ejecuta en Ubuntu, luego instala JDK 17, Android SDK y finalmente se configura la identidad de Git y el entorno local.

  Yaml

  runs-on: ubuntu-latest
  
  - name: Set up JDK 17
  uses: actions/setup-java@v4
  with:
  java-version: 17
  distribution: temurin
  
  - name: Set up Android SDK
  uses: android-actions/setup-android@v3
  
  - name: Configure Git identity
  run: |
  git config --global user.name "github-actions[bot]"
  git config --global user.email "github-actions[bot]@users.noreply.github.com"
  
  - name: Configure Android environment
  run: |
  echo "sdk.dir=$ANDROID_SDK_ROOT" > local.properties
  chmod +x ./gradlew
  
  

• Clonado del repositorio

  Este paso usa la acción oficial actions/checkout@v4 para clonar el repositorio dentro del entorno de ejecución del workflow (runner de GitHub Actions).

  Yaml

  - name: Checkout repository
  uses: actions/checkout@v4
  with:
  fetch-depth: 0
  

• Generación de la documentación

  Limpia salida previa y ejecuta Dokka.

  Yaml

  - name: Clean previous Dokka output
  run: rm -rf docs/dokka
  
  - name: Generate Dokka documentation
  run: ./gradlew clean dokkaGenerate --stacktrace --info
  

• Preparación para GitHub Pages

  Mueve la documentación generada a public/ y agrega .nojekyll.

  Yaml

  - name: Prepare public/ for GitHub Pages
  run: |
  rm -rf public
  mkdir public
  cp -r docs/dokka/. public/
  touch public/.nojekyll
  

• Despliegue a GitHub Pages

  Mueve la documentación generada a public/ y agrega .nojekyll.

  Yaml

  -- name: Deploy to GitHub Pages
  id: deployment
  uses: peaceiris/actions-gh-pages@v3
  with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
  publish_branch: gh-pages
  publish_dir: public
  force_orphan: true
  keep_files: false
  commit_message: "docs: Update documentation via GitHub Actions"
  
  

• Verificar Deploy

  Revisar el workflow en git hub Action

  

Vista previa proyecto desplegado