Skip to content

Commit 27c1baf

Browse files
tino1b2betino1b2be
committed
Add Javadoc site published to GitHub Pages
Aggregates Javadoc from the two published modules (:goertzel and :dtmf-core) into build/javadoc-site/ via a new root task, then deploys to GitHub Pages on every push to master. - build.gradle.kts: new `aggregateJavadoc` task. Copies each published module's javadoc under a subfolder (goertzel/, dtmf-core/) and writes an index.html landing page listing the modules with links to the source, requirements, and design docs - .github/workflows/pages.yml: runs aggregateJavadoc on ubuntu-latest, uploads the site as a Pages artifact, and deploys via actions/deploy-pages@v4. One deployment at a time (concurrency.group = pages with cancel-in-progress), triggered on push to master plus workflow_dispatch for manual reruns One-time setup required (not automatable from here): set Settings -> Pages -> Source to "GitHub Actions" on the repository. Without that, the deploy step will fail with "Pages source is set to a branch that doesn't exist" or similar. Verified locally: - ./gradlew aggregateJavadoc produces build/javadoc-site/ with goertzel/, dtmf-core/, and index.html - Each module's javadoc renders; the landing page links resolve
1 parent b227f6d commit 27c1baf

2 files changed

Lines changed: 165 additions & 0 deletions

File tree

‎.github/workflows/pages.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: Pages
2+
3+
# Builds and deploys the Javadoc site to GitHub Pages on every push to master.
4+
#
5+
# The aggregate-javadoc task at the root of the build (see build.gradle.kts)
6+
# combines :goertzel and :dtmf-core javadoc into build/javadoc-site/ with a
7+
# small landing page at the root. That directory is the Pages deployment
8+
# artifact.
9+
#
10+
# Pages is deployed via the official actions/deploy-pages@v4 flow; the repo
11+
# needs Settings -> Pages -> Source = "GitHub Actions" for this to work.
12+
13+
on:
14+
push:
15+
branches: [master]
16+
workflow_dispatch:
17+
18+
permissions:
19+
contents: read
20+
pages: write
21+
id-token: write
22+
23+
# Allow only one concurrent Pages deployment; cancel any in-progress run when
24+
# a newer commit lands on master.
25+
concurrency:
26+
group: pages
27+
cancel-in-progress: true
28+
29+
jobs:
30+
build:
31+
name: Build Javadoc site
32+
runs-on: ubuntu-latest
33+
steps:
34+
- name: Checkout repository
35+
uses: actions/checkout@v4
36+
37+
- name: Set up JDK 17 (Temurin)
38+
uses: actions/setup-java@v4
39+
with:
40+
distribution: temurin
41+
java-version: '17'
42+
43+
- name: Cache Gradle caches and wrapper dists
44+
uses: actions/cache@v4
45+
with:
46+
path: |
47+
~/.gradle/caches
48+
~/.gradle/wrapper
49+
key: ${{ runner.os }}-gradle-${{ hashFiles('gradle/wrapper/gradle-wrapper.properties', 'gradle/libs.versions.toml') }}
50+
restore-keys: |
51+
${{ runner.os }}-gradle-
52+
53+
- name: Aggregate Javadoc
54+
run: ./gradlew aggregateJavadoc --no-daemon
55+
56+
- name: Upload Pages artifact
57+
uses: actions/upload-pages-artifact@v3
58+
with:
59+
path: build/javadoc-site
60+
61+
deploy:
62+
name: Deploy to GitHub Pages
63+
needs: build
64+
runs-on: ubuntu-latest
65+
environment:
66+
name: github-pages
67+
url: ${{ steps.deployment.outputs.page_url }}
68+
steps:
69+
- name: Deploy to GitHub Pages
70+
id: deployment
71+
uses: actions/deploy-pages@v4

‎build.gradle.kts‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,97 @@ allprojects {
1616
group = "com.tino1b2be"
1717
version = "2.0.0"
1818
}
19+
20+
// -------------------------------------------------------------------------
21+
// Aggregate Javadoc for GitHub Pages
22+
// -------------------------------------------------------------------------
23+
//
24+
// The GitHub Pages workflow (.github/workflows/pages.yml) runs
25+
// `./gradlew aggregateJavadoc` on every push to master and deploys the
26+
// output at `build/javadoc-site/` as the project's Pages site. The task
27+
// merges every published module's main-source javadoc under a single
28+
// directory:
29+
//
30+
// build/javadoc-site/
31+
// index.html ← landing page listing the modules
32+
// goertzel/ ← :goertzel javadoc
33+
// dtmf-core/ ← :dtmf-core javadoc
34+
//
35+
// Consumers can browse the full API at tino1b2be.github.io/DTMF-Decoder.
36+
37+
val publishedModuleNames = setOf("goertzel", "dtmf-core")
38+
39+
tasks.register("aggregateJavadoc") {
40+
group = "documentation"
41+
description = "Aggregate Javadoc from every published module into build/javadoc-site/."
42+
43+
val siteDir = layout.buildDirectory.dir("javadoc-site")
44+
val publishedModules = subprojects.filter { it.name in publishedModuleNames }
45+
46+
dependsOn(publishedModules.map { "${it.path}:javadoc" })
47+
48+
val inputDirs = publishedModules.associate { module ->
49+
module.name to module.layout.buildDirectory.dir("docs/javadoc")
50+
}
51+
inputDirs.values.forEach { inputs.dir(it) }
52+
outputs.dir(siteDir)
53+
54+
doLast {
55+
val site = siteDir.get().asFile
56+
site.deleteRecursively()
57+
site.mkdirs()
58+
59+
inputDirs.forEach { (name, dirProvider) ->
60+
val source = dirProvider.get().asFile
61+
val target = site.resolve(name)
62+
source.copyRecursively(target, overwrite = true)
63+
}
64+
65+
val landing = site.resolve("index.html")
66+
landing.writeText(buildLandingHtml(publishedModules.map { it.name }))
67+
}
68+
}
69+
70+
fun buildLandingHtml(moduleNames: List<String>): String {
71+
val listItems = moduleNames.joinToString("\n") { name ->
72+
""" <li><a href="$name/index.html"><code>$name</code></a></li>"""
73+
}
74+
return """<!DOCTYPE html>
75+
<html lang="en">
76+
<head>
77+
<meta charset="utf-8">
78+
<title>DTMF-Decoder API documentation</title>
79+
<style>
80+
body { font-family: system-ui, -apple-system, sans-serif; max-width: 720px; margin: 3rem auto; padding: 0 1rem; color: #222; }
81+
h1 { margin-bottom: 0.25rem; }
82+
p.tagline { color: #666; margin-top: 0; }
83+
ul { padding-left: 1.5rem; line-height: 1.9; }
84+
code { background: #f3f3f3; padding: 0.1rem 0.35rem; border-radius: 3px; }
85+
a { color: #0a60c6; text-decoration: none; }
86+
a:hover { text-decoration: underline; }
87+
footer { margin-top: 3rem; padding-top: 1rem; border-top: 1px solid #eee; color: #888; font-size: 0.9rem; }
88+
</style>
89+
</head>
90+
<body>
91+
<h1>DTMF-Decoder</h1>
92+
<p class="tagline">A Java 17 library for detecting and generating DTMF signalling tones per ITU-T Q.23 and Q.24.</p>
93+
94+
<h2>API documentation</h2>
95+
<ul>
96+
$listItems
97+
</ul>
98+
99+
<h2>Project links</h2>
100+
<ul>
101+
<li><a href="https://github.com/tino1b2be/DTMF-Decoder">Source on GitHub</a></li>
102+
<li><a href="https://github.com/tino1b2be/DTMF-Decoder/blob/master/docs/requirements.md">Requirements</a></li>
103+
<li><a href="https://github.com/tino1b2be/DTMF-Decoder/blob/master/docs/design.md">Design</a></li>
104+
</ul>
105+
106+
<footer>
107+
Generated from the <code>master</code> branch on every push. Currently documenting version ${project.version}.
108+
</footer>
109+
</body>
110+
</html>
111+
"""
112+
}

0 commit comments

Comments
 (0)