Skip to content

Commit

Permalink
ci: use Dokka to generate API documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@benny123tw
benny123tw committed Jun 14, 2024
1 parent e66ecc8 commit f95c259
Show file tree
Hide file tree
Showing 6 changed files with 90 additions and 57 deletions.
8 changes: 4 additions & 4 deletions .github/workflows/1.pipeline.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ jobs:
# github.event_name == 'workflow_dispatch'
# && inputs.type != '...no release'

publish_sonatype:
publish_central_portal:
name: Publish artifact (Maven Central)
uses: ./.github/workflows/callable.publish-central-portal.yml
secrets: inherit
Expand All @@ -75,11 +75,11 @@ jobs:
|| github.ref_type == 'tag'
)
publish_javadoc:
name: Publish javadoc (GitHub Pages)
publish_dokka:
name: Publish dokka (GitHub Pages)
permissions:
contents: write
uses: ./.github/workflows/callable.publish-javadoc.yml
uses: ./.github/workflows/callable.publish-dokka.yml
needs: build
if: |
(
Expand Down
100 changes: 51 additions & 49 deletions ...ub/workflows/callable.publish-javadoc.yml → .github/workflows/callable.publish-dokka.yml
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
name: Publish javadoc (GitHub Pages)
name: Publish dokka (GitHub Pages)

on:
workflow_dispatch:
workflow_call:

jobs:
build_package_javadoc:
name: Generate Javadoc
build_package_dokka:
name: Generate Dokka
runs-on: ubuntu-latest
permissions:
contents: write
Expand All @@ -24,10 +24,13 @@ jobs:
with:
cache-read-only: true

- name: Generate javadoc (gradle)
run: ./gradlew javadoc
# - name: Generate javadoc (gradle)
# run: ./gradlew javadoc

- name: Conclude javadoc version and set env
- name: Generate dokka HTML documentation
run: ./gradlew dokkaHtmlMultiModule

- name: Conclude dokka version and set env
run: |
if [[ "$GITHUB_REF" == "refs/heads/main" || "$GITHUB_REF" == "refs/heads/master" ]]; then
echo "PUBLISH_VERSION=current" >> $GITHUB_ENV
Expand All @@ -38,23 +41,23 @@ jobs:
- name: Conclude library name and set env
run: echo "LIBRARY_NAME=$(grep -o '^rootProject.name.*' settings.gradle.kts | sed -e 's/rootProject.name.*"\(.*\)"/\1/')" >> $GITHUB_ENV

- name: zip javadoc folder
- name: zip dokka folder
env:
LIBRARY_NAME: ${{ env.LIBRARY_NAME }}
run: |
cd "vite-spring-webmvc/build/docs/javadoc"
zip -r ../../../../javadoc.zip .
cd "build/dokka/htmlMultiModule"
zip -r ../../../dokka.zip .
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: javadoc.zip
path: javadoc.zip
name: dokka.zip
path: dokka.zip

deploy_javadoc:
deploy_dokka:
name: Deploy (GH Pages)
runs-on: ubuntu-latest
needs: build_package_javadoc
needs: build_package_dokka
permissions:
contents: write
steps:
Expand All @@ -69,7 +72,7 @@ jobs:
git fetch origin gh-pages || true
git checkout gh-pages || git switch --orphan gh-pages
- name: Conclude javadoc version and set env
- name: Conclude dokka version and set env
run: |
if [[ "$GITHUB_REF" == "refs/heads/main" || "$GITHUB_REF" == "refs/heads/master" ]]; then
echo "PUBLISH_VERSION=current" >> $GITHUB_ENV
Expand All @@ -81,75 +84,74 @@ jobs:
env:
GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
run: |
echo "<!DOCTYPE html><html lang=en><meta content=\"text/html; charset=utf-8\"http-equiv=Content-Type><meta content=\"index redirect\"name=description><link href=/$GITHUB_REPOSITORY_NAME/javadoc/ rel=canonical><link href=stylesheet.css rel=stylesheet title=Style><script>window.location.replace(\"/$GITHUB_REPOSITORY_NAME/javadoc/\")</script><noscript><meta content=0;/$GITHUB_REPOSITORY_NAME/javadoc/ http-equiv=Refresh></noscript><main role=main><noscript><p>JavaScript is disabled on your browser.</p></noscript><p><a href=/$GITHUB_REPOSITORY_NAME/javadoc/ >/$GITHUB_REPOSITORY_NAME/javadoc/</a></main>" > index.html
echo "<!DOCTYPE html><html lang=en><meta content=\"text/html; charset=utf-8\"http-equiv=Content-Type><meta content=\"index redirect\"name=description><link href=/$GITHUB_REPOSITORY_NAME/docs/ rel=canonical><link href=stylesheet.css rel=stylesheet title=Style><script>window.location.replace(\"/$GITHUB_REPOSITORY_NAME/docs/\")</script><noscript><meta content=0;/$GITHUB_REPOSITORY_NAME/docs/ http-equiv=Refresh></noscript><main role=main><noscript><p>JavaScript is disabled on your browser.</p></noscript><p><a href=/$GITHUB_REPOSITORY_NAME/docs/ >/$GITHUB_REPOSITORY_NAME/docs/</a></main>" > index.html
- name: Download artifact from build job
uses: actions/download-artifact@v4
with:
name: javadoc.zip
name: dokka.zip

- name: unzip javadoc folder
- name: unzip dokka folder
env:
PUBLISH_VERSION: ${{ env.PUBLISH_VERSION }}
run: |
mkdir -p javadoc
rm -Rf "javadoc/$PUBLISH_VERSION" || true
unzip -d "javadoc/$PUBLISH_VERSION" javadoc.zip
rm javadoc.zip
mkdir -p docs
rm -Rf "docs/$PUBLISH_VERSION" || true
unzip -d "docs/$PUBLISH_VERSION" dokka.zip
rm dokka.zip
- name: Create javadoc index.html listing versions
- name: Create dokka index.html listing versions
env:
PUBLISH_VERSION: ${{ env.PUBLISH_VERSION }}
GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
run: |
mkdir -p javadoc
rm javadoc/index.html || true
touch javadoc/index.html
mkdir -p docs
rm docs/index.html || true
touch docs/index.html
versions=( $(cd javadoc && find . -maxdepth 1 -type d | jq -srR 'split("\n") | unique | .[][2:] | select(length > 0)') )
versions=( $(cd docs && find . -maxdepth 1 -type d | jq -srR 'split("\n") | unique | .[][2:] | select(length > 0)') )
echo "javadoc versions:"
echo "docs versions:"
for value in "${versions[@]}"
do
echo "- $value"
done
echo "<!DOCTYPE HTML>" >> javadoc/index.html
echo "<html lang=\"en\">" >> javadoc/index.html
echo "<head>" >> javadoc/index.html
echo " <title>Javadoc | '$GITHUB_REPOSITORY_NAME'</title>" >> javadoc/index.html
echo " <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">" >> javadoc/index.html
echo " <meta charset=\"UTF-8\">" >> javadoc/index.html
echo " <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">" >> javadoc/index.html
echo " <meta http-equiv=\"X-UA-Compatible\" content=\"ie=edge\">" >> javadoc/index.html
echo " <meta name=\"description\" content=\"Javadoc for library '$GITHUB_REPOSITORY_NAME'\">" >> javadoc/index.html
echo "</head>" >> javadoc/index.html
echo "<body>" >> javadoc/index.html
echo "<main style=\"font-family: sans-serif;\">" >> javadoc/index.html
echo " <h1>Javadoc</h1>" >> javadoc/index.html
echo " <h2>Versions</h2>" >> javadoc/index.html
echo " <ul>" >> javadoc/index.html
echo "<!DOCTYPE HTML>" >> docs/index.html
echo "<html lang=\"en\">" >> docs/index.html
echo "<head>" >> docs/index.html
echo " <title>Dokka | '$GITHUB_REPOSITORY_NAME'</title>" >> docs/index.html
echo " <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">" >> docs/index.html
echo " <meta charset=\"UTF-8\">" >> docs/index.html
echo " <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">" >> docs/index.html
echo " <meta http-equiv=\"X-UA-Compatible\" content=\"ie=edge\">" >> docs/index.html
echo " <meta name=\"description\" content=\"Dokka for library '$GITHUB_REPOSITORY_NAME'\">" >> docs/index.html
echo "</head>" >> docs/index.html
echo "<body>" >> docs/index.html
echo "<main style=\"font-family: sans-serif;\">" >> docs/index.html
echo " <h1>Dokka</h1>" >> docs/index.html
echo " <h2>Versions</h2>" >> docs/index.html
echo " <ul>" >> docs/index.html
for value in "${versions[@]}"
do
echo " <li><a href=\"$value\">$value</a></li>" >> javadoc/index.html
echo " <li><a href=\"$value\">$value</a></li>" >> docs/index.html
done
echo " </ul>" >> javadoc/index.html
echo "</main>" >> javadoc/index.html
echo "</body>" >> javadoc/index.html
echo "</html>" >> javadoc/index.html
echo " </ul>" >> docs/index.html
echo "</main>" >> docs/index.html
echo "</body>" >> docs/index.html
echo "</html>" >> docs/index.html
- name: Commit files
run: |
git config --local user.email "action@github.com"
git config --local user.name "GitHub Action"
git add .
git status
git diff-index --quiet HEAD || git commit -m "chore: updates index.html files incl. javadoc versions"
git diff-index --quiet HEAD || git commit -m "chore: updates index.html files incl. dokka versions"
# Push changes
- name: Push changes
run: |
git push --set-upstream origin gh-pages
6 changes: 6 additions & 0 deletions .idea/kotlinc.xml
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

16 changes: 16 additions & 0 deletions build.gradle.kts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ import com.vanniktech.maven.publish.SonatypeHost
plugins {
`java-library`
alias(libs.plugins.publish.maven)
alias(libs.plugins.dokka)
kotlin("jvm") version "2.0.0" apply false
}

description = "Java library for Vite integration."
Expand All @@ -14,6 +16,20 @@ allprojects {
}
}

subprojects {
apply(plugin = "org.jetbrains.kotlin.jvm")
apply(plugin = "org.jetbrains.dokka")

tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>().configureEach {
dokkaSourceSets {
configureEach {
sourceRoots.from(file("src/main/java"))
}
}
}

}

mavenPublishing {
publishToMavenCentral(SonatypeHost.CENTRAL_PORTAL)

Expand Down
7 changes: 3 additions & 4 deletions gradle/libs.versions.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,8 @@ jarkata_servlet_jsp = "4.0.0-M2"
junit = "5.10.2"
assertj = "3.26.0"
testcontainers = "1.19.8"
publish_plugin = "2.0.0"
publish_maven_plugin = "0.28.0"
release_plugin = "3.0.2"
dokka = "1.9.20"

[libraries]
junit = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
Expand All @@ -34,6 +33,6 @@ testcontainers_junit = ["testcontainers", "testcontainers_junit5"]
[plugins]
spring_boot = { id = "org.springframework.boot", version.ref = "springframework_boot" }
spring_dependency_management = { id = "io.spring.dependency-management", version.ref = "spring_dependency_management" }
publish = { id = "io.github.gradle-nexus.publish-plugin", version.ref = "publish_plugin" }
publish_maven = { id = "com.vanniktech.maven.publish", version.ref = "publish_maven_plugin" }
release = { id = "net.researchgate.release", version.ref = "release_plugin" }
dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" }

10 changes: 10 additions & 0 deletions vite-spring-webmvc/build.gradle.kts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,16 @@ dependencies {
testImplementation(libs.junit)
}

configurations.matching { it.name.startsWith("dokka") }.configureEach {
resolutionStrategy.eachDependency {
if (requested.group.startsWith("com.fasterxml.jackson")) {
// override jackson for Dokka as a workaround
// see: https://github.com/Kotlin/dokka/issues/3472
useVersion("2.15.3")
}
}
}

tasks.named<Test>("test") {
// Use JUnit Platform for unit tests.
useJUnitPlatform()
Expand Down

0 comments on commit f95c259

Please sign in to comment.