Skip to content

MathieuSoysal/Javadoc-publisher.yml

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Deploy Publish JavaDoc

Public workflows that use this action. Test Actions (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.

GitHub-Page-settings

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

Command to test your changes

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

Contributors

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.