(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.
- Your project need to use Maven or Gradle.
| 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 |
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 commandThe 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: gradleIf 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 .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 commandRemember 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.
[](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.
Want to contribute to Javadoc Publisher? Awesome! Check out the contributing guidelines to get involved.
- 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
act workflow_dispatch -W .github/workflows/test-action-local.yml -P ubuntu-latest=quay.io/jamezp/act-maven
If you like or use this project, please remember to give it a star ⭐️. Thanks!
The Dockerfile and associated scripts and documentation in this project are released under the Apache 2.0 License.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "github-actions[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent