API Documentation

Relevant source files

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	Value	Purpose
`additionalOptions`	`--snippet-path=${project.basedir}/src/demo/java`	Enable code snippets from demo classes
`debug`	`true`	Verbose output for troubleshooting
`detectLinks`	`true`	Auto-detect external Javadoc links
`doclint`	`none`	Disable strict HTML/reference checking
`docfilessubdirs`	`true`	Process subdirectories in doc-files
`failOnError`	`false`	Continue build on documentation errors
`show`	`public`	Document only public API surface

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

BOM Installation (.github/workflows/apidocs.yml25-26)
- Installs Bill of Materials to establish version constraints
- Required for consistent dependency resolution across modules
Project Installation (.github/workflows/apidocs.yml27)
- Installs all project artifacts with -Dquickly profile
- Skips tests and other time-consuming validations
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)
Source Aggregation (.github/workflows/apidocs.yml30-32)
- Executes three Antrun plugin targets in sequence
- Copies dependency graph, sources, and demo code
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

Parameter	Value	Purpose
`token`	`${{ secrets.PUBLISH_CONTENT }}`	GitHub Personal Access Token with cross-repo write access
`repository-name`	`patternfly-java/apidocs`	Target repository for documentation
`branch`	`gh-pages`	Branch hosting GitHub Pages content
`folder`	`./apidoc/target/reports/apidocs`	Local directory containing generated docs
`clean`	`true`	Remove previous content before deployment
`force`	`true`	Force push even if remote has diverged
`single-commit`	`true`	Squash all changes into one commit

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