Skip to content

Commit ff364db

Browse files
biplab1biplab1
committed
feat(docs-generator): add Dokka documentation generation templates
1 parent e7c96a7 commit ff364db

File tree

5 files changed

+1039
-0
lines changed

5 files changed

+1039
-0
lines changed

‎.github/workflows/docs-generate.yaml‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
name: Generate and Publish Documentation
2+
3+
# Workflow to generate Dokka documentation and push to docs repository
4+
# This workflow runs on push to main/dev branch or can be triggered manually
5+
6+
on:
7+
push:
8+
branches:
9+
- dev
10+
paths:
11+
- 'core/**'
12+
- 'feature/**'
13+
- 'cmp-*/**'
14+
- 'docs-generator/**'
15+
- '.github/workflows/docs-generate.yaml'
16+
17+
pull_request:
18+
branches:
19+
- dev
20+
paths:
21+
- 'core/**'
22+
- 'feature/**'
23+
- 'cmp-*/**'
24+
- 'docs-generator/**'
25+
26+
workflow_dispatch:
27+
inputs:
28+
publish:
29+
description: 'Publish documentation to docs repository'
30+
required: false
31+
default: 'true'
32+
type: boolean
33+
34+
env:
35+
JAVA_VERSION: '17'
36+
DOCS_REPO: 'YOUR_USERNAME/YOUR_DOCS_REPO' # Update with your docs repository
37+
DOCS_BRANCH: 'main'
38+
39+
jobs:
40+
generate-documentation:
41+
name: Generate Documentation
42+
runs-on: ubuntu-latest
43+
44+
permissions:
45+
contents: read
46+
packages: read
47+
48+
steps:
49+
- name: Checkout repository
50+
uses: actions/checkout@v4
51+
with:
52+
fetch-depth: 0 # Full history for better documentation links
53+
54+
- name: Set up JDK ${{ env.JAVA_VERSION }}
55+
uses: actions/setup-java@v4
56+
with:
57+
distribution: 'temurin'
58+
java-version: ${{ env.JAVA_VERSION }}
59+
cache: 'gradle'
60+
61+
- name: Grant execute permission for gradlew
62+
run: chmod +x gradlew
63+
64+
- name: Setup Gradle
65+
uses: gradle/actions/setup-gradle@v3
66+
with:
67+
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
68+
69+
# Generate Dokka documentation
70+
- name: Generate Dokka Documentation
71+
run: ./gradlew dokkaHtmlMultiModule --no-daemon --stacktrace
72+
continue-on-error: false
73+
74+
# Organize documentation
75+
- name: Organize Documentation Output
76+
run: |
77+
mkdir -p docs-output
78+
79+
# Copy Dokka documentation
80+
if [ -d "build/dokka" ]; then
81+
echo "Copying Dokka documentation..."
82+
cp -r build/dokka/* docs-output/
83+
fi
84+
85+
# Create .nojekyll for GitHub Pages
86+
touch docs-output/.nojekyll
87+
88+
echo "Documentation organized successfully!"
89+
ls -la docs-output/
90+
91+
# Upload documentation as artifact
92+
- name: Upload Documentation Artifact
93+
uses: actions/upload-artifact@v4
94+
with:
95+
name: documentation
96+
path: docs-output/
97+
retention-days: 30
98+
99+
# Publish to GitHub Pages or docs repository
100+
- name: Publish to Documentation Repository
101+
if: |
102+
github.event_name == 'push' &&
103+
github.ref == 'refs/heads/main' &&
104+
(github.event.inputs.publish != 'false')
105+
env:
106+
DOCS_DEPLOY_TOKEN: ${{ secrets.DOCS_DEPLOY_TOKEN }}
107+
run: |
108+
if [ -z "$DOCS_DEPLOY_TOKEN" ]; then
109+
echo "⚠️ DOCS_DEPLOY_TOKEN not set. Skipping documentation publishing."
110+
echo "To enable publishing, add DOCS_DEPLOY_TOKEN to repository secrets."
111+
exit 0
112+
fi
113+
114+
# Configure git
115+
git config --global user.name "github-actions[bot]"
116+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
117+
118+
# Clone docs repository
119+
git clone "https://x-access-token:${DOCS_DEPLOY_TOKEN}@github.com/${DOCS_REPO}.git" docs-repo
120+
cd docs-repo
121+
git checkout "${DOCS_BRANCH}" || git checkout -b "${DOCS_BRANCH}"
122+
123+
# Clear existing docs and copy new ones
124+
rm -rf *
125+
cp -r ../docs-output/* .
126+
127+
# Create .nojekyll for GitHub Pages
128+
touch .nojekyll
129+
130+
# Commit and push
131+
git add .
132+
if git diff --staged --quiet; then
133+
echo "No documentation changes to publish"
134+
else
135+
git commit -m "📚 Update documentation from ${GITHUB_REPOSITORY}@${GITHUB_SHA::7}"
136+
git push origin "${DOCS_BRANCH}"
137+
echo "✅ Documentation published successfully!"
138+
fi
139+
140+
# Summary
141+
- name: Generate Summary
142+
if: always()
143+
run: |
144+
echo "### 📚 Documentation Generation Summary" >> $GITHUB_STEP_SUMMARY
145+
echo "" >> $GITHUB_STEP_SUMMARY
146+
echo "| Component | Status |" >> $GITHUB_STEP_SUMMARY
147+
echo "|-----------|--------|" >> $GITHUB_STEP_SUMMARY
148+
echo "| Dokka (Kotlin API Docs) | ✅ Generated |" >> $GITHUB_STEP_SUMMARY
149+
echo "" >> $GITHUB_STEP_SUMMARY
150+
echo "**Commit:** \`${GITHUB_SHA::7}\`" >> $GITHUB_STEP_SUMMARY
151+
echo "**Branch:** \`${GITHUB_REF_NAME}\`" >> $GITHUB_STEP_SUMMARY
152+
153+
if [ "${{ github.event_name }}" == "push" ] && [ "${{ github.ref }}" == "refs/heads/main" ]; then
154+
echo "" >> $GITHUB_STEP_SUMMARY
155+
echo "📦 Documentation artifact uploaded and available for 30 days" >> $GITHUB_STEP_SUMMARY
156+
fi
157+
158+
# Optional: Validate documentation links
159+
validate-docs:
160+
name: Validate Documentation
161+
runs-on: ubuntu-latest
162+
needs: generate-documentation
163+
if: github.event_name == 'pull_request'
164+
165+
steps:
166+
- name: Download Documentation Artifact
167+
uses: actions/download-artifact@v4
168+
with:
169+
name: documentation
170+
path: docs-output/
171+
172+
- name: Check Documentation Size
173+
run: |
174+
SIZE=$(du -sh docs-output/ | cut -f1)
175+
echo "📊 Documentation size: $SIZE"
176+
echo "### Documentation Validation" >> $GITHUB_STEP_SUMMARY
177+
echo "Documentation size: **$SIZE**" >> $GITHUB_STEP_SUMMARY
178+
179+
- name: List Generated Files
180+
run: |
181+
echo "### 📁 Generated Files" >> $GITHUB_STEP_SUMMARY
182+
echo '```' >> $GITHUB_STEP_SUMMARY
183+
find docs-output/ -type f | head -20 >> $GITHUB_STEP_SUMMARY
184+
echo '```' >> $GITHUB_STEP_SUMMARY

‎docs-generator/README.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Documentation Generator
2+
3+
> **Note**: This is a documentation generation template for projects created from this KMP template. Follow the setup instructions below to enable documentation generation in your project.
4+
5+
## Quick Setup (For New Projects)
6+
7+
### 1. Add Dokka to Version Catalog
8+
9+
Edit `gradle/libs.versions.toml`:
10+
11+
**In `[versions]` section (after Static Analysis section), add:**
12+
```toml
13+
# Documentation
14+
dokka = "2.0.0"
15+
```
16+
17+
**In `[plugins]` section (before Room Plugin), add:**
18+
```toml
19+
# Documentation
20+
dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" }
21+
```
22+
23+
### 2. Apply Dokka in Root Build
24+
25+
Edit `build.gradle.kts`:
26+
27+
**In plugins block, add:**
28+
```kotlin
29+
alias(libs.plugins.dokka) apply false
30+
```
31+
32+
**At end of file, add:**
33+
```kotlin
34+
// Apply Dokka configuration for documentation generation
35+
apply(from = "docs-generator/dokka-config/dokka.gradle.kts")
36+
```
37+
38+
### 3. Customize for Your Project
39+
40+
Edit `docs-generator/dokka-config/dokka.gradle.kts` and replace:
41+
- `YOUR_USERNAME/YOUR_REPO` with your actual GitHub repository
42+
43+
### 4. Generate Documentation
44+
45+
```bash
46+
./docs-generator/scripts/generate-docs.sh
47+
```
48+
49+
Documentation output: `build/docs-output/`
50+
51+
## What's Included
52+
53+
```
54+
docs-generator/
55+
├── dokka-config/ # Dokka configuration templates
56+
├── scripts/ # Generation and publishing scripts
57+
└── README.md # This file
58+
59+
.github/workflows/
60+
└── docs-generate.yaml # CI/CD automation
61+
```
62+
63+
## Optional: Automated Publishing
64+
65+
1. Create a separate docs repository
66+
2. Add `DOCS_DEPLOY_TOKEN` secret to your GitHub repo
67+
3. Update `DOCS_REPO` in `.github/workflows/docs-generate.yaml`
68+
4. Push to main - docs auto-publish!
69+
70+
## Available Scripts
71+
72+
```bash
73+
# Generate documentation
74+
./docs-generator/scripts/generate-docs.sh
75+
76+
# Generate with cleanup
77+
./docs-generator/scripts/generate-docs.sh --clean
78+
79+
# Publish to docs repository
80+
./docs-generator/scripts/push-to-docs-repo.sh
81+
82+
# Dry run (see what would happen)
83+
./docs-generator/scripts/push-to-docs-repo.sh --dry-run
84+
```
85+
86+
## If You Don't Need Documentation
87+
88+
Delete these:
89+
- `docs-generator/` folder
90+
- `.github/workflows/docs-generate.yaml`
91+
92+
## Documentation Best Practices
93+
94+
1. Add KDoc comments to all public APIs
95+
2. Include usage examples in documentation
96+
3. Link related APIs using `@see` tags
97+
4. Test documentation locally before publishing
98+
99+
## Troubleshooting
100+
101+
**Docs not generating?**
102+
- Ensure Dokka plugin is applied in `build.gradle.kts`
103+
- Run with: `./gradlew dokkaHtmlMultiModule --stacktrace`
104+
105+
**Publishing fails?**
106+
- Check `DOCS_DEPLOY_TOKEN` secret is set
107+
- Verify token has `repo` permissions
108+
- Confirm docs repository URL is correct
109+
110+
## Further Reading
111+
112+
- [Dokka Documentation](https://kotlinlang.org/docs/dokka-introduction.html)
113+
- [KDoc Syntax](https://kotlinlang.org/docs/kotlin-doc.html)
114+
- [GitHub Pages](https://docs.github.com/en/pages)
115+

0 commit comments

Comments
 (0)