Skip to content

JAVADOC_PUBLISHING.md

Latest commit

 

History

History
283 lines (215 loc) · 7.92 KB

JAVADOC_PUBLISHING.md

File metadata and controls

283 lines (215 loc) · 7.92 KB
Raw

JavaDoc Publishing Guide

This document explains how platform-java publishes API documentation to GitHub Pages.

Overview

The platform-java project automatically generates and publishes JavaDoc to GitHub Pages at:
https://flossware.github.io/platform-java/

This provides:

  • Browsable API documentation for all modules
  • Search functionality for classes and methods
  • Professional landing page with navigation
  • Version information and metadata
  • Module index for easy navigation

Architecture

GitHub Actions Workflow

The workflow (.github/workflows/javadoc.yml) is triggered by:

  1. Tag pushes - When a release tag is created (e.g., 1.1, 1.2)
  2. Manual dispatch - Via GitHub Actions UI for on-demand generation

Workflow Steps:

  1. Check out repository code
  2. Set up JDK 21 and Maven cache
  3. Generate aggregate JavaDoc with mvn javadoc:aggregate
  4. Extract version information from POM
  5. Create enhanced landing page with custom HTML/CSS
  6. Generate API module index
  7. Verify JavaDoc generation
  8. Upload to GitHub Pages artifact
  9. Deploy to GitHub Pages environment

Maven Configuration

POM Setup:

  • Parent POM (pom.xml) configures:
    • maven-javadoc-plugin v3.6.3 with aggregate goal
    • maven-site-plugin v3.12.1 for site generation
    • JavaDoc options: source=21, doclint=none, HTML5 output
    • Search feature enabled for Java 9+ JavaDoc
    • Custom tags (apiNote, implSpec, implNote)
    • Links to Oracle Java 21 documentation

Output Structure

target/site/apidocs/
├── index.html                 # Custom landing page
├── index-all.html            # Full API index (generated)
├── modules.html              # Module navigation page
├── version.txt               # Version metadata
├── org/flossware/platform/
│   ├── api/                  # API documentation
│   ├── core/                 # Core platform docs
│   ├── classloader/          # ClassLoader docs
│   ├── threadpool/           # Thread pool docs
│   ├── security/             # Security docs
│   ├── monitoring/           # Monitoring docs
│   ├── messaging/            # Messaging docs
│   ├── rest/                 # REST API docs
│   └── metrics/              # Metrics docs
└── resources/                # Stylesheets and assets

GitHub Pages Configuration

Repository Settings

Required Configuration:

  1. Go to Repository Settings → Pages
  2. Set Source to: Deploy from a branch
  3. Select Branch: gh-pages
  4. Select Folder: / (root)
  5. Enforce HTTPS: ✓ (recommended)

Domain (Optional):

  • Custom domain support available if configured
  • Default: https://github.com/FlossWare/platform-java/ pages will be available at https://flossware.github.io/platform-java/

Branch Management

The workflow automatically:

  1. Generates JavaDoc artifacts
  2. Creates/updates the gh-pages branch
  3. Publishes to the configured GitHub Pages URL
  4. Maintains artifact history (no manual cleanup needed)

Features

1. Professional Landing Page

Custom HTML5 landing page with:

  • Responsive design (mobile-friendly)
  • Dark mode support via CSS media queries
  • Gradient backgrounds
  • Quick access buttons to API docs
  • Feature list highlighting key platform capabilities
  • Version information loaded dynamically

2. Search Functionality

JavaDoc search is enabled (Java 9+ feature):

  • Full-text search of classes, methods, fields
  • Quick navigation to API members
  • Available in the generated index-all.html

3. API Module Index

Dedicated modules.html page with:

  • List of all major platform modules
  • Direct links to package documentation
  • Brief descriptions of each module
  • Easy navigation between modules

4. Version Metadata

Generated version.txt includes:

  • Release version number
  • Generation timestamp (UTC)
  • Git reference and commit SHA
  • Used to populate dynamic landing page content

5. Enhanced JavaDoc Configuration

Maven JavaDoc plugin configured with:

  • HTML5 output - Modern semantic HTML
  • Search enabled - Quick class/method lookup
  • Custom tags - @apiNote, @implSpec, @implNote
  • External links - Links to Java 21 standard library docs
  • Encoding - UTF-8 for international characters
  • Custom footer - GPL v3 license attribution

Usage

For Developers

View Latest JavaDoc:

https://flossware.github.io/platform-java/

Search for a Class:

  1. Open the JavaDoc site
  2. Click "Browse API Documentation"
  3. Use search box (Java 9+ feature)

Navigate by Module:

  1. Go to https://flossware.github.io/platform-java/modules.html
  2. Click module name to view its documentation

For CI/CD

Manual Trigger:

# Trigger workflow via GitHub CLI
gh workflow run javadoc.yml

Automatic Trigger on Release:

# Create and push a release tag
git tag 1.2
git push origin 1.2
# Workflow automatically publishes JavaDoc

Customization

Modifying the Landing Page

Edit .github/workflows/javadoc.yml in the "Create enhanced landing page" step:

  • Update HTML content, styling, and structure
  • Modify colors, fonts, and layout
  • Add or remove features and links

Customizing JavaDoc Output

Edit pom.xml maven-javadoc-plugin configuration:

  • Change window title: <windowtitle>
  • Modify footer: <bottom>
  • Add/remove custom tags
  • Adjust search settings: <searchEnabled>

Adding Custom Stylesheets

To add custom CSS:

  1. Create a stylesheet in a resource directory
  2. Copy it to the output directory in workflow
  3. Link it in the custom index.html

Enhancements

Current Implementation (v1.0)

✅ Automatic generation on release tags
✅ Professional landing page
✅ JavaDoc search functionality
✅ Module navigation page
✅ Version metadata tracking
✅ GitHub Pages deployment
✅ Dark mode CSS support
✅ Mobile responsive design

Potential Future Enhancements

  • Versioned Documentation - Separate docs per release version

    • Implement version subdirectories (e.g., /1.1/, /1.2/)
    • Create version selector on landing page
    • Maintain documentation history

  • Advanced Styling

    • Custom theme matching project branding
    • Syntax highlighting improvements
    • Dark mode toggle (not just system preference)

  • Documentation Integration

    • Link from README.md to JavaDoc
    • Include architectural guides
    • Add quickstart examples

  • Search Index

    • Full-text search across all documentation
    • Elasticsearch integration for advanced search
    • Cross-module navigation

Troubleshooting

JavaDoc Generation Fails

Issue: Workflow shows "Generation failed"

Solutions:

  1. Check Maven compilation succeeds locally: 
    mvn clean javadoc:aggregate -DskipTests
  2. Verify all modules are in parent pom.xml
  3. Check for Javadoc syntax errors in source code

Pages Not Updating

Issue: Changes don't appear on GitHub Pages

Solutions:

  1. Verify workflow ran successfully (check Actions tab)
  2. Wait 1-2 minutes for GitHub Pages to rebuild
  3. Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
  4. Check Repository → Pages → Source is correctly configured

Workflow Permission Errors

Issue: "Permission denied" when deploying

Solutions:

  1. Verify workflow has correct permissions: 
    permissions:
  contents: read
  pages: write
  id-token: write
  2. Check repository Settings → Actions → General → Workflow Permissions
  3. Ensure "Read and write permissions" is selected

Related Documentation

License

JavaDoc documentation is published under the same license as the platform-java source code (GNU GPL v3).

Last Updated: 2024
Maintained By: FlossWare Development Team
Status: Production Ready