Deploy Publish JavaDoc

(Tested on Java 8, 11, 17, 19, 21, Maven, Gradle, Ubuntu, macOS, Windows)

Automatically generate Javadoc from your Java project and publish it to GitHub Page.

Requirements

• Your project need to use Maven or Gradle.

Inputs

input	description	default
java-version	java version inside your project	17
GITHUB_TOKEN	The GitHub token the GitHub repository
deploy-mode	Deploy mode can be branch or artifact	branch
javadoc-branch	Branch where the javadoc is hosted	javadoc
target-folder	Directory where the javadoc contents should be stored	.
java-distribution	Java distribution inside your project	adopt
project	Maven or Gradle project	maven
custom-command	Custom command to generate the javadoc	""
subdirectories	Custom subdirectories to upload from
without-deploy	Enable or disable deploy of the javadoc to the GitHub Page	false
without-checkout	Enable or disable the checkout	false
javadoc-source-folder	The folder where our project generate the JavaDoc	target/site/apidocs

Usage

For Maven project

The workflow, usually declared in .github/workflows/publish-javadoc.yml, looks like:

.github/workflows/publish-javadoc-maven.yml

name: Deploy Javadoc

on:
  push:
    branches:
      - master
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # if you have a protection rule on your repository, you'll need to give write permission to the workflow.
    steps:
      - name: Deploy JavaDoc 🚀
        uses: MathieuSoysal/[email protected]
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          javadoc-branch: javadoc
          java-version: 17
          target-folder: javadoc # url will be https://<username>.github.io/<repo>/javadoc, This can be left as nothing to generate javadocs in the root folder.
          project: maven # or gradle
          # subdirectories: moduleA moduleB #for subdirectories support, needs to be run with custom command

For Gradle project

The workflow, usually declared in .github/workflows/publish-javadoc.yml, looks like:

.github/workflows/publish-javadoc-gradle.yml

name: Deploy Javadoc

on:
  push:
    branches:
      - master
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # if you have a protection rule on your repository, you'll need to give write permission to the workflow.
    steps:
      - name: Deploy JavaDoc 🚀
        uses: MathieuSoysal/[email protected]
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          javadoc-branch: javadoc
          java-version: 17
          target-folder: javadoc
          project: gradle

With custom command for generating Javadoc

If you want to use a custom command for generating Javadoc, you can use the custom-command input. This input is a string that will be executed in the root of your project. For example, if you want to use the javadoc command, you can use the following workflow:

.github/workflows/publish-javadoc-custom-command.yml

name: Deploy Javadoc

on:
  push:
    branches:
      - master
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # if you have a protection rule on your repository, you'll need to give write permission to the workflow.
    steps:
      - name: Deploy JavaDoc 🚀
        uses: MathieuSoysal/[email protected]
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          javadoc-branch: javadoc
          java-version: 17
          target-folder: javadoc
          project: gradle
          custom-command: javadoc -d javadoc -sourcepath src/main/java -subpackages .

Deploy with artifact

If you want to deploy the javadoc as an artifact, you can use the deploy-mode input. Set the deploy-mode to artifact and the javadoc will be deployed as an artifact, so you don't need a javadoc branch.

name: Deploy Javadoc

on:
  push:
    branches:
      - master
      - main
concurrency:
  group: pages
  cancel-in-progress: false
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      permissions:
        contents: read
        pages: write
        id-token: write
    steps:
      - name: Deploy JavaDoc 🚀
        uses: MathieuSoysal/[email protected]
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          deploy-mode: artifact
          java-version: 17
          project: maven # or gradle
          # subdirectories: moduleA moduleB #for subdirectories support, needs to be run with custom command

GitHub page

Remember to configure your repository settings with your new GitHub Page. 😉

Help to set up the GitHub Pages settings in your repository

If you need to use the specified directory to store the javadoc, You need to do this on your Settings page. Like this.

Not only that, but if you have README.md file in your javadoc branch, the access will show up just as well. and doing so does not affect the javadoc commit.

Badge

[![Javadoc](https://img.shields.io/badge/JavaDoc-Online-green)](https://YOUR-USERNAME.github.io/YOUR-REPO/javadoc/)

In the badge link, replace YOUR-USERNAME with your GitHub Username and replace YOUR-REPO with the name of your GitHub repository.

Contributing

Want to contribute to Javadoc Publisher? Awesome! Check out the contributing guidelines to get involved.

Requirements to your environment to test in locally

• Install nektos/act & clone the repo git clone [email protected]:MathieuSoysal/Javadoc-publisher.yml.git
  OR
• Use the devcontainer of the repo: with GitHub Codespaces

Command to test your changes

act workflow_dispatch -W .github/workflows/test-action-local.yml -P ubuntu-latest=quay.io/jamezp/act-maven

Contributors

Stars 🎇

If you like or use this project, please remember to give it a star ⭐️. Thanks!

License

The Dockerfile and associated scripts and documentation in this project are released under the Apache 2.0 License.