[P3] Publish JavaDoc website to GitHub Pages

[sfloess]

Problem

JavaDoc is generated but not published to a publicly accessible website.

Impact

• Severity: LOW
• Category: Documentation/Developer Experience
• Developers must build JavaDoc locally
• No browsable API documentation online
• Reduces discoverability of APIs

Proposed Solution

Publish JavaDoc to GitHub Pages at:
https://flossware.github.io/platform-java/

Implementation

1. Generate JavaDoc Site

mvn javadoc:aggregate

2. GitHub Actions Workflow

name: Publish JavaDoc

on:
  push:
    tags: ['*']

jobs:
  javadoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
      
      - name: Generate JavaDoc
        run: mvn javadoc:aggregate
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./target/site/apidocs

3. Enable GitHub Pages

Repository Settings → Pages → Source: gh-pages branch

Additional Enhancements

1. Versioned JavaDoc: Separate docs for each release (1.1, 1.2, etc.)
2. Search: Enable JavaDoc search feature
3. Dark Mode: Custom CSS for dark mode
4. Link from README: Add badge and link in README.md

[![JavaDoc](https://img.shields.io/badge/JavaDoc-1.1-blue)](https://flossware.github.io/platform-java/)

Examples

• Spring Framework: https://docs.spring.io/spring-framework/docs/current/javadoc-api/
• Apache Commons: https://commons.apache.org/proper/commons-lang/apidocs/

Priority

P3 - Low - Nice to have for v1.2, should have for v1.3.

Related

• JavaDoc generation already configured in parent POM ✅
• Maven Site Plugin already configured ✅