Skip to content

Commit 6db190d

Browse files
bsboddenbsbodden
committed
feat(docs): integrate Javadoc into Antora documentation site
 - Add aggregated Javadoc generation tasks for redis-om-spring and redis-om-spring-ai modules - Create API reference page with navigation links to module documentation - Configure Antora attachments integration for Javadoc HTML files - Update GitHub Actions workflow to generate and deploy Javadoc automatically - Add build scripts for local Javadoc generation and validation - Exclude generated Javadoc files from version control via .gitignore - Implement cleanup mechanisms for proper build artifact management
1 parent cade687 commit 6db190d

File tree

16 files changed

+963
-16
lines changed

16 files changed

+963
-16
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,24 @@ jobs:
9191
echo "Antora playbook content:"
9292
cat docs/antora-playbook.yml
9393
94+
- name: Generate Javadoc Documentation
95+
run: |
96+
echo "Cleaning any existing generated Javadoc files..."
97+
rm -rf docs/content/modules/ROOT/attachments/javadoc
98+
rm -rf docs/content/modules/ROOT/assets/javadoc
99+
100+
echo "Generating Javadoc for all modules..."
101+
./gradlew aggregateJavadoc generateModuleJavadocs
102+
103+
# Verify Javadoc generation
104+
if [ ! -d "build/docs/javadoc" ]; then
105+
echo "ERROR: Javadoc generation failed"
106+
exit 1
107+
fi
108+
109+
echo "Javadoc generated successfully:"
110+
find build/docs/javadoc -name "index.html" -type f | head -10
111+
94112
- name: Build Documentation
95113
run: |
96114
./gradlew :docs:generateSite
@@ -100,6 +118,10 @@ jobs:
100118
npm install
101119
./node_modules/.bin/antora --fetch --stacktrace --log-format=pretty antora-playbook.yml --to-dir=build/site
102120
fi
121+
122+
# Verify Javadoc assets are included
123+
echo "Checking for Javadoc assets in site:"
124+
find docs/build/site -path "*/javadoc/*" -name "index.html" | head -5 || echo "No Javadoc assets found"
103125
104126
- name: Verify Build Output
105127
run: |

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,10 @@ docs/node_modules/
3535
docs/node/
3636
docs/build/
3737

38+
# Generated Javadoc documentation (build artifacts)
39+
docs/content/modules/ROOT/attachments/javadoc/
40+
docs/content/modules/ROOT/assets/javadoc/
41+
3842
**/.claude/settings.local.json
3943
/out/
4044
build/

‎build.gradle‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,64 @@ tasks.register('aggregateTestReport', TestReport) {
3131
}
3232
)
3333
}
34+
35+
// Add aggregated Javadoc generation
36+
tasks.register('aggregateJavadoc', Javadoc) {
37+
description = 'Generate aggregated Javadoc for all modules'
38+
group = 'documentation'
39+
40+
source subprojects.findAll {
41+
it.name in [
42+
'redis-om-spring',
43+
'redis-om-spring-ai'
44+
]
45+
}.collect { it.sourceSets.main.allJava }
46+
classpath = files(subprojects.findAll {
47+
it.name in [
48+
'redis-om-spring',
49+
'redis-om-spring-ai'
50+
]
51+
}.collect { it.sourceSets.main.compileClasspath })
52+
destinationDir = layout.buildDirectory.dir("docs/javadoc/aggregate").get().asFile
53+
54+
options {
55+
title = "Redis OM Spring ${project.version} API"
56+
windowTitle = "Redis OM Spring ${project.version}"
57+
author = true
58+
version = true
59+
use = true
60+
splitIndex = true
61+
links(
62+
'https://docs.oracle.com/en/java/javase/21/docs/api/',
63+
'https://docs.spring.io/spring-framework/docs/current/javadoc-api/',
64+
'https://docs.spring.io/spring-data/redis/docs/current/api/',
65+
'https://docs.spring.io/spring-boot/docs/current/api/'
66+
)
67+
}
68+
69+
// Ensure Javadoc generation succeeds
70+
failOnError = false
71+
}
72+
73+
// Individual module Javadocs
74+
tasks.register('generateModuleJavadocs') {
75+
description = 'Generate Javadoc for individual modules'
76+
group = 'documentation'
77+
78+
def moduleProjects = subprojects.findAll {
79+
it.name in [
80+
'redis-om-spring',
81+
'redis-om-spring-ai'
82+
]
83+
}
84+
dependsOn moduleProjects.collect { "${it.name}:javadoc" }
85+
86+
doLast {
87+
moduleProjects.each { project ->
88+
copy {
89+
from project.tasks.javadoc.destinationDir
90+
into layout.buildDirectory.dir("docs/javadoc/modules/${project.name}").get().asFile
91+
}
92+
}
93+
}
94+
}

‎docs/Makefile‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Redis OM Spring Documentation Makefile
2+
# Provides convenient commands for local development
3+
4+
.PHONY: help build build-fast serve test validate clean stop
5+
6+
# Default target
7+
help:
8+
@echo "Redis OM Spring Documentation Commands"
9+
@echo "======================================"
10+
@echo ""
11+
@echo "Development Commands:"
12+
@echo " make build - Build complete documentation with Javadoc (recommended)"
13+
@echo " make build-fast - Build documentation without Javadoc (faster)"
14+
@echo " make serve - Build and serve documentation locally at http://localhost:8000"
15+
@echo " make test - Run comprehensive local testing"
16+
@echo " make validate - Validate Javadoc integration"
17+
@echo ""
18+
@echo "Maintenance Commands:"
19+
@echo " make clean - Clean all build artifacts"
20+
@echo " make stop - Stop Docker container"
21+
@echo ""
22+
@echo "Quick Start:"
23+
@echo " make serve # Build everything and start local server"
24+
@echo ""
25+
26+
# Build complete documentation with Javadoc integration
27+
build:
28+
@echo "🔨 Building complete documentation with Javadoc integration..."
29+
cd .. && ./gradlew :docs:build
30+
@echo "✅ Build complete! Documentation is in build/site/"
31+
32+
# Build documentation without Javadoc (faster for content development)
33+
build-fast:
34+
@echo "🔨 Building documentation without Javadoc (faster)..."
35+
@echo "⚠️ Note: API Reference links will be broken without Javadoc"
36+
npx antora antora-playbook.yml --to-dir=build/site
37+
@echo "✅ Fast build complete! Documentation is in build/site/"
38+
39+
# Build and serve with Docker
40+
serve: build
41+
@echo "🐳 Starting local documentation server..."
42+
@echo "📖 Documentation will be available at http://localhost:8000"
43+
@echo ""
44+
@echo "📄 Key URLs:"
45+
@echo " Main Site: http://localhost:8000"
46+
@echo " Current Docs: http://localhost:8000/redis-om-spring/current/"
47+
@echo " API Reference: http://localhost:8000/redis-om-spring/current/api-reference.html"
48+
@echo ""
49+
@echo "Press Ctrl+C to stop the server"
50+
docker-compose up
51+
52+
# Run comprehensive testing
53+
test:
54+
@echo "🧪 Running comprehensive local testing..."
55+
./scripts/test-local-docs.sh
56+
57+
# Validate Javadoc integration
58+
validate:
59+
@echo "✅ Validating Javadoc integration..."
60+
./scripts/validate-javadoc.sh
61+
62+
# Clean all build artifacts
63+
clean:
64+
@echo "🧹 Cleaning build artifacts..."
65+
cd .. && ./gradlew clean
66+
rm -rf build/site
67+
rm -rf content/modules/ROOT/assets/javadoc
68+
rm -rf node_modules/.cache
69+
@echo "✅ Clean complete!"
70+
71+
# Stop Docker container
72+
stop:
73+
@echo "🛑 Stopping documentation server..."
74+
docker-compose down
75+
@echo "✅ Server stopped!"
76+
77+
# Development workflow targets
78+
dev-setup: clean build
79+
@echo "🚀 Development environment ready!"
80+
@echo " Run 'make serve' to start the server"
81+
82+
# Quick validation for CI/development
83+
quick-test: build validate
84+
@echo "✅ Quick validation complete!"

‎docs/README.md‎

Lines changed: 81 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -18,31 +18,56 @@ npm install
1818

1919
### Building the Site
2020

21-
#### Using Gradle
21+
#### Using Gradle (Recommended)
2222

2323
```bash
24-
# From the project root
24+
# From the project root - includes Javadoc generation
2525
./gradlew :docs:build
2626

2727
# From the docs directory
2828
../gradlew build
2929
```
3030

31-
The documentation will be built in the `build/site` directory.
31+
This builds both the documentation site and integrates the API documentation (Javadoc) automatically. The documentation will be built in the `build/site` directory.
3232

33-
#### Using npm directly
33+
#### Building with Javadoc Integration
34+
35+
To explicitly build with all API documentation:
36+
37+
```bash
38+
# Generate Javadoc first, then build docs
39+
./gradlew aggregateJavadoc generateModuleJavadocs :docs:build
40+
41+
# Or build everything in one command (same as above)
42+
./gradlew :docs:build
43+
```
44+
45+
**Important**: Javadoc files are generated dynamically during the build process and are **NOT** checked into the repository. They are created fresh each time you build and are properly ignored by Git.
46+
47+
#### Using npm directly (without Javadoc)
3448

3549
```bash
3650
npx antora antora-playbook.yml --to-dir=build/site
3751
```
3852

53+
**Note**: Building with npm directly will not include API documentation (Javadoc). Use the Gradle method for complete documentation including API references.
54+
3955
### Viewing the Documentation
4056

4157
After building, you can view the documentation by opening any of these files in your browser:
4258

4359
- `build/site/index.html` - Documentation homepage
4460
- `build/site/redis-om-spring/current/index.html` - Current version documentation
4561
- `build/site/redis-om-spring/current/overview.html` - Overview page
62+
- `build/site/redis-om-spring/current/api-reference.html` - API Reference page (includes Javadoc links)
63+
64+
#### API Documentation Access
65+
66+
When built with Gradle (including Javadoc), the API documentation is available at:
67+
68+
- **Complete API**: `build/site/redis-om-spring/current/_attachments/javadoc/aggregate/index.html`
69+
- **Core Module**: `build/site/redis-om-spring/current/_attachments/javadoc/modules/redis-om-spring/index.html`
70+
- **AI Module**: `build/site/redis-om-spring/current/_attachments/javadoc/modules/redis-om-spring-ai/index.html`
4671

4772
## Content Structure
4873

@@ -70,17 +95,38 @@ The repository includes a Docker setup that uses Nginx to serve the documentatio
7095
#### Serving with Docker
7196

7297
```bash
73-
# First build the site
74-
./gradlew :docs:build
75-
# or
76-
npx antora antora-playbook.yml --to-dir=build/site
77-
78-
# Then serve with Docker (run from the docs directory)
79-
docker compose up -d
98+
# Option 1: Using Makefile (recommended)
99+
cd docs
100+
make serve
101+
102+
# Option 2: Manual steps
103+
./gradlew :docs:build # Build with Javadoc integration
104+
cd docs
105+
docker compose up -d # Start container
80106
```
81107

82108
The documentation will be available at http://localhost:8000.
83109

110+
**Important**: Use `./gradlew :docs:build` to ensure API documentation is included. Using `npx antora` directly will serve the site without Javadoc integration.
111+
112+
#### Quick Testing
113+
114+
For comprehensive local testing including Javadoc validation:
115+
116+
```bash
117+
cd docs
118+
make test
119+
# or manually:
120+
./scripts/test-local-docs.sh
121+
```
122+
123+
This script will:
124+
- Build the complete documentation with Javadoc
125+
- Validate all API documentation is present
126+
- Start the Docker container
127+
- Test all key URLs
128+
- Provide direct links for testing
129+
84130
#### Docker Configuration
85131

86132
The Docker setup uses:
@@ -104,6 +150,8 @@ If you encounter issues with the Docker setup:
104150
2. Check if port 8000 is already in use on your machine
105151
3. Verify Docker and Docker Compose are installed correctly
106152
4. Look at the Docker logs with `docker-compose logs` or `docker logs roms-documentation`
153+
5. For missing API documentation, ensure you built with `./gradlew :docs:build` (not npm directly)
154+
6. Validate Javadoc integration with `./docs/scripts/validate-javadoc.sh`
107155

108156
### Adding New Content
109157

@@ -143,7 +191,28 @@ To add a new page:
143191
- Include more examples from demo applications
144192
- Standardize page structure and formatting
145193
- Add navigation breadcrumbs
146-
- Integrate automated API documentation
194+
- ~~Integrate automated API documentation~~ ✅ **Complete** (Javadoc integration implemented)
195+
196+
## Javadoc Integration
197+
198+
The documentation site includes automated API reference generation:
199+
200+
### ✅ **Build Process**
201+
- Javadoc files are **generated dynamically** during build (NOT checked into repository)
202+
- Integrated into Antora as attachments for proper URL handling
203+
- Automatic generation in GitHub Actions workflow
204+
- Local builds regenerate fresh Javadoc
205+
206+
### 📁 **Repository Management**
207+
- Generated files are properly ignored in `.gitignore`
208+
- Source code comments are the source of truth
209+
- No manual maintenance of API documentation required
210+
- Fresh generation ensures docs stay synchronized with code
211+
212+
### 🔧 **Local Development**
213+
- Use `make clean && make serve` for full rebuild with Javadoc
214+
- Use validation script: `./scripts/validate-javadoc.sh`
215+
- Clean generated files: `./scripts/clean-generated-javadoc.sh`
147216

148217
## Versioning
149218

‎docs/antora-playbook.yml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,9 @@ asciidoc:
2727
idseparator: '-'
2828
page-pagination: ''
2929
toc: ~
30-
xrefstyle: short
30+
xrefstyle: short
31+
# Javadoc-specific attributes
32+
javadoc-base-url: '{attachmentsdir}/javadoc'
33+
javadoc-core-url: '{javadoc-base-url}/modules/redis-om-spring'
34+
javadoc-ai-url: '{javadoc-base-url}/modules/redis-om-spring-ai'
35+
javadoc-aggregate-url: '{javadoc-base-url}/aggregate'

‎docs/build.gradle‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,26 @@ task installAntora(type: NpmTask) {
3434
]
3535
}
3636

37+
// Add Javadoc integration task
38+
task copyJavadocs(type: Copy) {
39+
description = 'Copy Javadoc outputs to Antora attachments'
40+
group = 'documentation'
41+
42+
dependsOn ':aggregateJavadoc', ':generateModuleJavadocs'
43+
44+
from rootProject.layout.buildDirectory.dir('docs/javadoc')
45+
into "${project.projectDir}/content/modules/ROOT/attachments/javadoc"
46+
47+
doFirst {
48+
mkdir "${project.projectDir}/content/modules/ROOT/attachments"
49+
mkdir "${project.projectDir}/content/modules/ROOT/attachments/javadoc"
50+
logger.lifecycle("Copying Javadoc documentation to Antora attachments...")
51+
}
52+
}
53+
3754
// Generate Antora site
3855
task generateSite(type: NodeTask) {
39-
dependsOn installAntora
56+
dependsOn installAntora, copyJavadocs
4057
script = file('node_modules/@antora/cli/bin/antora')
4158

4259
// Add options to handle multi-version gracefully
@@ -66,4 +83,6 @@ assemble.dependsOn generateSite
6683
clean {
6784
delete 'node_modules'
6885
delete project.buildDir
86+
delete "${project.projectDir}/content/modules/ROOT/assets/javadoc"
87+
delete "${project.projectDir}/content/modules/ROOT/attachments/javadoc"
6988
}

0 commit comments

Comments
 (0)