API Documentation

This document describes the API documentation generation system for PatternFly Java, covering the aggregation strategy, build configuration, and publishing workflows. The API documentation is generated using Javadoc and published to a dedicated GitHub Pages repository.

For information about the showcase application and component demonstrations, see Showcase Application Development. For details on the overall release process, see Release Process.

Documentation Architecture

PatternFly Java uses a centralized aggregation approach to generate comprehensive API documentation across all modules. The apidoc module serves as an artificial aggregator that collects sources from multiple modules and produces a unified Javadoc output.

Key Design Decisions:

• Single aggregated output provides a cohesive browsing experience across all modules
• Source copying strategy enables inclusion of demo snippets and proper package organization
• Minimal dependencies in the apidoc module itself to avoid classpath pollution
• GitHub Pages deployment to a dedicated repository for stable documentation URLs

Published Location: https://patternfly-java.github.io/apidocs/

Module Structure

The apidoc module (apidoc/pom.xml1-164) is a special-purpose packaging module that:

• Inherits from patternfly-java-code-parent
• Declares minimal dependencies (only Elemento libraries for type resolution)
• Uses Maven Antrun plugin to copy sources from all modules
• Configures Maven Javadoc plugin to generate aggregate documentation

Sources: apidoc/pom.xml1-164

Source Aggregation Strategy

The documentation build process aggregates Java sources from multiple modules into a single directory structure before generating Javadoc. This ensures all classes appear in a unified package hierarchy with proper cross-references.

Copy Operations

Three distinct copy operations execute before Javadoc generation:

1. Copy Doc Files

Copies the Maven dependency graph image to the documentation assets directory (apidoc/pom.xml66-78):

• Source: dependency-graph.png (root directory)
• Target: src/main/javadoc/doc-files/dependency-graph.png
• Used in package documentation and overview pages

2. Copy Sources

Aggregates all Java source files from production modules (apidoc/pom.xml79-114):

• Target directory: src/main/java/org/patternfly/
• Includes all **/*.java files from:
  • charts/src/main/java/org/patternfly/
  • components/src/main/java/org/patternfly/
  • core/src/main/java/org/patternfly/
  • extensions/codeeditor/src/main/java/org/patternfly/
  • extensions/finder/src/main/java/org/patternfly/
  • icons/src/main/java/org/patternfly/
  • layouts/src/main/java/org/patternfly/
  • tokens/src/main/java/org/patternfly/

3. Copy Demos

Aggregates demonstration code for snippet inclusion (apidoc/pom.xml115-132):

• Target directory: src/demo/java
• Includes all **/*.java files from:
  • core/src/demo/java
  • components/src/demo/java
• Used via --snippet-path to enable {@snippet} tags in Javadoc

Sources: apidoc/pom.xml61-134

Javadoc Configuration

The Maven Javadoc plugin is configured with several customizations to produce high-quality, well-linked documentation.

Plugin Configuration

Configuration Reference: apidoc/pom.xml138-160

External API Links

The documentation includes links to external libraries, enabling users to navigate directly to dependency documentation:

Configured Links (apidoc/pom.xml145-155):

• Elemento: https://hal.github.io/elemento/apidocs/
• GWT Project: https://www.gwtproject.org/javadoc/latest/
• gwt-event: https://javadoc.io/doc/org.gwtproject.event/gwt-event/
• gwt-safehtml: https://javadoc.io/doc/org.gwtproject.safehtml/gwt-safehtml/
• elemental2-core: https://javadoc.io/doc/com.google.elemental2/elemental2-core/
• elemental2-dom: https://javadoc.io/doc/com.google.elemental2/elemental2-dom/
• elemental2-promise: https://javadoc.io/doc/com.google.elemental2/elemental2-promise/
• elemental2-webstorage: https://javadoc.io/doc/com.google.elemental2/elemental2-webstorage/

Source Exclusions

Demo classes are excluded from the final documentation to keep the API surface clean (apidoc/pom.xml157-159):

• Excludes: **/*Demo.java
• Demo code is used only for snippet extraction, not included in generated docs

Sources: apidoc/pom.xml135-164

Build Process

The API documentation build follows a specific sequence to ensure all prerequisites are met before Javadoc generation.

Build Steps

1. BOM Installation (.github/workflows/apidocs.yml25-26)

   • Installs Bill of Materials to establish version constraints
   • Required for consistent dependency resolution across modules

2. Project Installation (.github/workflows/apidocs.yml27)

   • Installs all project artifacts with -Dquickly profile
   • Skips tests and other time-consuming validations

3. Dependency Graph Generation (.github/workflows/apidocs.yml28)

   • Generates dependency-graph.png at project root
   • Uses depgraph:aggregate Maven goal
   • Requires Graphviz installation (.github/workflows/apidocs.yml16)

4. Source Aggregation (.github/workflows/apidocs.yml30-32)

   • Executes three Antrun plugin targets in sequence
   • Copies dependency graph, sources, and demo code

5. Javadoc Generation (.github/workflows/apidocs.yml33)

   • Executes mvn javadoc:javadoc in apidoc directory
   • Produces HTML documentation in target/reports/apidocs

Sources: .github/workflows/apidocs.yml25-34 .github/workflows/release.yml86-95

Publishing Workflows

API documentation is published to GitHub Pages through two workflows: automatic release publishing and manual on-demand publishing.

Automatic Release Publishing

Triggered by version tags matching v* pattern (.github/workflows/release.yml3-6):

Workflow Details (.github/workflows/release.yml71-104):

• Job name: publish-apidocs
• Runs in parallel with BOM/artifact deployment
• Uses dedicated PUBLISH_CONTENT token for cross-repository deployment
• Deploys to external repository: patternfly-java/apidocs
• Target branch: gh-pages
• Clean deployment: Replaces all previous content
• Single commit: Squashes entire documentation into one commit

Manual Publishing

Triggered via GitHub Actions UI using workflow_dispatch (.github/workflows/apidocs.yml3-4):

Key Differences from Release Workflow:

• Can be triggered independently without a release
• Useful for documentation-only updates
• Same build and deployment process as release workflow
• No dependency on artifact deployment jobs

Deployment Configuration

Authentication Note: The default GITHUB_TOKEN cannot write to external repositories, requiring a custom Personal Access Token stored in PUBLISH_CONTENT secret (.github/workflows/release.yml98 .github/workflows/apidocs.yml37).

Sources: .github/workflows/release.yml71-104 .github/workflows/apidocs.yml1-43

Clean Operations

The apidoc module configures Maven Clean plugin to remove both generated source directories and the standard target directory (apidoc/pom.xml49-60):

Cleaned Directories:

• src/demo - Copied demonstration code
• src/main/java - Aggregated production sources

This ensures each build starts with a clean slate, preventing stale sources from previous builds from affecting the documentation.

Sources: apidoc/pom.xml49-60

Accessing the Documentation

Published URL

https://patternfly-java.github.io/apidocs/

Repository Structure

• Source Repository: https://github.com/patternfly-java/patternfly-java
• Documentation Repository: https://github.com/patternfly-java/apidocs
• Documentation Branch: gh-pages

Documentation Contents

The published documentation includes:

• Package summaries for all PatternFly Java packages
• Class documentation for all public classes
• Method and field documentation with inline code examples
• Dependency graph showing module relationships
• Cross-references to external library documentation (Elemento, GWT, Elemental2)

Update Frequency

Documentation is updated:

• Automatically on every release (version tag push)
• Manually via workflow dispatch when needed for documentation improvements

Sources: .github/workflows/release.yml71-104 .github/workflows/apidocs.yml1-43