Skip to content

Latest commit

 

History

History
121 lines (91 loc) · 3.64 KB

README.md

File metadata and controls

121 lines (91 loc) · 3.64 KB
Raw

📘 Introduction

This GitHub Action automates the deployment of Javadoc documentation to GitHub Pages. It builds your Java project, generates Javadoc, and publishes it to a specified branch, typically gh-pages.

✨ Features

  • Automatic Javadoc Generation: Automatically builds the project and generates Javadoc documentation.
  • Customizable Branch: Allows publishing of Javadoc to a specified branch (default is gh-pages).
  • Flexible JDK Configuration: Supports multiple JDK versions and distributions, allowing for easy customization.
  • Optional Test Skipping: Configurable option to skip tests during the build process.
  • Branch Cleanup: Ability to clean up old branches before publishing, ensuring a fresh deployment environment.

⚙️ Inputs

The following inputs can be configured for this action:

GITHUB_TOKEN

  • Description: GitHub token used for repository access and authentication.
  • Required: Yes

BRANCH

  • Description: The branch where the Javadoc documentation will be published. Defaults to 'gh-pages'.
  • Required: No
  • Default: 'gh-pages'

BRANCH_CLEANUP

  • Description: Whether to clean up old branches before publishing. Set to 'true' to delete the old branch. Defaults to 'false'.
  • Required: No
  • Default: 'false'

JAVA_VERSION

  • Description: The version of Java your project is using (e.g., 17).
  • Required: Yes
  • Default: '17'

JAVA_DISTRIBUTION

  • Description: The JDK distribution to use (e.g., 'adopt', 'zulu'). Defaults to 'adopt'.
  • Required: No
  • Default: 'adopt'

SKIP_TESTS

  • Description: Whether to skip tests during the build process. Set to 'true' to skip tests.
  • Required: No
  • Default: 'false'

DOC_DIRECTORY

  • Description: The directory where the Javadoc documentation is generated. Defaults to 'target/site/apidocs'.
  • Required: No
  • Default: 'target/site/apidocs'

🚀 Usage

To use this GitHub Action, create a workflow YAML file in your repository's .github/workflows directory.

Example Workflow

Below is an example workflow that builds the project, generates Javadoc, and publishes it to the gh-pages branch:

name: Deploy Javadoc to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy-javadoc:
    runs-on: ubuntu-latest

    steps:
      - name: Check out the repository
        uses: actions/checkout@v4

      - name: Deploy Javadoc
        uses: DashioDevs/action-javadocs-deploy@v1
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          JAVA_VERSION: '17'
          JAVA_DISTRIBUTION: 'adopt'
          SKIP_TESTS: 'false'
          DOC_DIRECTORY: 'target/site/apidocs'
          BRANCH: 'gh-pages'
          BRANCH_CLEANUP: 'false'

Example with Branch Cleanup

To clean up old branches before publishing, set the BRANCH_CLEANUP input to 'true':

name: Deploy Javadoc to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy-javadoc:
    runs-on: ubuntu-latest

    steps:
      - name: Check out the repository
        uses: actions/checkout@v4

      - name: Deploy Javadoc
        uses: DashioDevs/action-javadocs-deploy@v1
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          JAVA_VERSION: '17'
          JAVA_DISTRIBUTION: 'adopt'
          SKIP_TESTS: 'false'
          DOC_DIRECTORY: 'target/reports/apidocs'
          BRANCH: 'gh-pages'
          BRANCH_CLEANUP: 'true'

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.