Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mathieusoysal/javadoc-publisher.yml
Generate Javadoc from your maven/gradle project and deploy it with GitHub Page.
https://github.com/mathieusoysal/javadoc-publisher.yml
collaborate github github-page github-pages gradle hacktoberfest java java11 java16 java17 java18 java8 javadoc javadoc-publish maven
Last synced: about 3 hours ago
JSON representation
Generate Javadoc from your maven/gradle project and deploy it with GitHub Page.
- Host: GitHub
- URL: https://github.com/mathieusoysal/javadoc-publisher.yml
- Owner: MathieuSoysal
- License: apache-2.0
- Created: 2021-12-25T17:04:07.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-11T01:31:30.000Z (about 1 month ago)
- Last Synced: 2024-09-24T03:33:38.413Z (about 15 hours ago)
- Topics: collaborate, github, github-page, github-pages, gradle, hacktoberfest, java, java11, java16, java17, java18, java8, javadoc, javadoc-publish, maven
- Language: Java
- Homepage:
- Size: 5.16 MB
- Stars: 42
- Watchers: 4
- Forks: 18
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Deploy Publish JavaDoc
[](https://github.com/search?o=desc&q=MathieuSoysal+javadoc-publisher+path%3A.github%2Fworkflows+language%3AYAML&s=&type=code)
[](https://github.com/MathieuSoysal/publish-javadoc/actions/workflows/test-action-final.yml)
*(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
```YAML
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://.github.io//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
```YAML
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
```YAML
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.
```YAML
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.
![]()
[
](https://user-images.githubusercontent.com/43273304/230144277-3714a61b-640e-49d4-b164-47598de8734b.jpg)
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
```Markdown
[](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](CONTRIBUTING.md) to get
involved.
### Requirements to your environment to test in locally
- Install [nektos/act](https://github.com/nektos/act) & clone the
repo `git clone [email protected]:MathieuSoysal/Javadoc-publisher.yml.git`
OR
- Use the devcontainer of the repo:
with [GitHub Codespaces](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=441722764)
### Command to test your changes
```bash
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](https://github.com/MathieuSoysal/publish-javadoc/blob/main/LICENSE).