Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: deploy with actions artifact #82

Merged
merged 2 commits into from
May 15, 2024
Merged

feat: deploy with actions artifact #82

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d36193b
feat: deploy with actions artifact
brenoepics Apr 28, 2024
b4004ac
Merge branch 'main' into feat-1
brenoepics May 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 66 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
# Deploy Publish JavaDoc

[![Public workflows that use this action.](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi-endbug.vercel.app%2Fapi%2Fgithub-actions%2Fused-by%3Faction%3DMathieuSoysal%2FJavadoc-publisher%26badge%3Dtrue)](https://github.com/search?o=desc&q=MathieuSoysal+javadoc-publisher+path%3A.github%2Fworkflows+language%3AYAML&s=&type=code)
[![Test Actions](https://github.com/MathieuSoysal/publish-javadoc/actions/workflows/test-action-final.yml/badge.svg)](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 needs to use **Maven** or **Gradle**.

- Your project need to use **Maven** or **Gradle**.

<details>
<summary>
<h2>Inputs</h2>
Expand All @@ -17,6 +19,7 @@ Automatically generate Javadoc from your Java project and publish it to GitHub P
|-----------------------|------------------------------------------------------------|---------------------|
| 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 |
Expand Down Expand Up @@ -64,6 +67,7 @@ jobs:
project: maven # or gradle
# subdirectories: moduleA moduleB #for subdirectories support, needs to be run with custom command
```

</details>

### For Gradle project
Expand All @@ -73,8 +77,6 @@ The workflow, usually declared in `.github/workflows/publish-javadoc.yml`, looks
<details open>
<summary>.github/workflows/publish-javadoc-gradle.yml</summary>



```YAML
name: Deploy Javadoc

Expand All @@ -96,14 +98,19 @@ jobs:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
javadoc-branch: javadoc
java-version: 17
target-folder: javadoc
target-folder: javadoc
project: gradle
```

</details>

### 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:
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:

<details open>
<summary>.github/workflows/publish-javadoc-custom-command.yml</summary>
Expand All @@ -129,12 +136,48 @@ jobs:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
javadoc-branch: javadoc
java-version: 17
target-folder: javadoc
target-folder: javadoc
project: gradle
custom-command: javadoc -d javadoc -sourcepath src/main/java -subpackages .
```

</details>

### 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/Javadoc-publisher.yml@v2.5.0
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. 😉
Expand All @@ -145,30 +188,34 @@ Remember to configure your repository settings with your new GitHub Page. 😉

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


![]()
[<img src="https://user-images.githubusercontent.com/43273304/230144277-3714a61b-640e-49d4-b164-47598de8734b.jpg" width="900" alt="GitHub-Page-settings" />](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.
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.
</details>

### Badge

```Markdown
[![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.

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.
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 git@github.com: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)
- Install [nektos/act](https://github.com/nektos/act) & clone the
repo `git clone git@github.com: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

Expand All @@ -177,11 +224,14 @@ act workflow_dispatch -W .github/workflows/test-action-local.yml -P ubuntu-lates
```

## Contributors

<img src="CONTRIBUTORS.svg" alt="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).

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).
61 changes: 26 additions & 35 deletions action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,23 @@ inputs:
description: "Java version inside your project"
required: true
default: "17"
type: string
GITHUB_TOKEN: # GitHub Token
description: "The GitHub token the GitHub repository"
required: true
deploy-mode: # deploy mode
description: "Deploy mode branch or artifact"
required: true
default: "branch"

# Optional inputs
javadoc-branch: # branch where the javadoc is hosted
description: "Branch where the javadoc is hosted"
required: true
required: false
default: javadoc
type: string
target-folder: # target folder for the javadoc contents
description: "Directory where the javadoc contents should be stored"
required: true
required: false
default: .
type: string

# Optional inputs
java-distribution: # distribution of java
description: "Java distribution inside your project"
required: false
Expand All @@ -35,37 +36,27 @@ inputs:
description: "Maven or Gradle project"
required: false
default: maven
type: choice
options:
- maven
- gradle
custom-command:
description: "Custom command to generate the javadoc"
required: false
default: ""
type: string
subdirectories:
description: "Custom subdirectories to upload from"
required: false
type: array
javadoc-source-folder:
description: "Custom path for the new Javadoc"
required: false
default: target/site/apidocs
type: string

# Development and testing inputs
without-deploy: # deploy the javadoc to the GitHub Page, is used for development testing with nektos/act
description: "Enable or disable deploy of the javadoc to the GitHub Page"
required: false
default: "false"
type: boolean
without-checkout: # checkout the javadoc branch, is used for development testing with nektos/act
description: "Enable or disable the checkout"
required: false
default: "false"
type: boolean


runs:
using: "composite"
Expand All @@ -90,7 +81,7 @@ runs:
if: inputs.project == 'gradle' && inputs.custom-command == ''
run: gradle javadoc
shell: bash

- name: Generate Javadoc with custom command
if: inputs.custom-command != ''
run: ${{ inputs.custom-command }}
Expand All @@ -103,7 +94,7 @@ runs:
mkdir -p ${{ inputs.javadoc-source-folder }}
fi
dirs=$(echo ${{ inputs.subdirectories }} | tr " " "\n")

for dir in $dirs
do
mkdir -p ${{ inputs.javadoc-source-folder }}/$dir
Expand All @@ -112,33 +103,33 @@ runs:
ls -R ${{ inputs.javadoc-source-folder }}
shell: bash

- name: Deploy to GitHub Page 🚀 with Maven
if: ${{ inputs.without-deploy == 'false' && inputs.project == 'maven' }}
uses: JamesIves/github-pages-deploy-action@v4.6.0
with:
token: ${{ inputs.GITHUB_TOKEN }}
branch: ${{ inputs.javadoc-branch }}
clean: true
folder: ${{ inputs.javadoc-source-folder }}
target-folder: ${{ inputs.target-folder }}

- name: Set Javadoc source folder for Gradle
- name: Set Javadoc source folder
id: set-javadoc-source-folder
if: ${{ inputs.project == 'gradle' }}
run: |
if [ ${{ inputs.javadoc-source-folder }} == "target/site/apidocs" ]; then
if [ ${{ inputs.project }} == "gradle" && ${{ inputs.javadoc-source-folder }} == "target/site/apidocs" ]; then
echo "javadoc-source-folder=build/docs/javadoc" >> "$GITHUB_OUTPUT"
else
echo "javadoc-source-folder=${{ inputs.javadoc-source-folder }}" >> "$GITHUB_OUTPUT"
fi
fi
shell: bash

- name: Deploy to GitHub Page 🚀 with Gradle
if: ${{ inputs.without-deploy == 'false' && inputs.project == 'gradle' }}
- name: Deploy to GitHub Page Branch 🚀
if: ${{ inputs.deploy-mode == 'branch' && inputs.without-deploy == 'false' }}
uses: JamesIves/github-pages-deploy-action@v4.6.0
with:
token: ${{ inputs.GITHUB_TOKEN }}
branch: ${{ inputs.javadoc-branch }}
clean: true
folder: ${{ steps.set-javadoc-source-folder.outputs.javadoc-source-folder }}
target-folder: ${{ inputs.target-folder }}

- name: Deploy to GitHub Page Artifact 🚀
if: ${{ inputs.deploy-mode == 'artifact' && inputs.without-deploy == 'false' }}
uses: actions/upload-pages-artifact@v3
with:
path: ${{ steps.set-javadoc-source-folder.outputs.javadoc-source-folder }}

- name: Deploy to GitHub Pages
if: ${{ inputs.deploy-mode == 'artifact' && inputs.without-deploy == 'false' }}
id: deployment
uses: actions/deploy-pages@v4
Loading