From d36193bc8b4ac0ee30a79ad1b4c99a4ae6da8cc7 Mon Sep 17 00:00:00 2001 From: "Breno A." Date: Sun, 28 Apr 2024 17:39:04 -0300 Subject: [PATCH] feat: deploy with actions artifact --- README.md | 81 ++++++++++++++++++++++++++++++++++++++++++++---------- action.yml | 61 ++++++++++++++++++---------------------- 2 files changed, 92 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index d536e5b..b74858c 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,14 @@ # 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, Maven, Gradle, Ubuntu, Macos, Windows)* +[![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, 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

@@ -15,6 +18,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 | @@ -62,6 +66,7 @@ jobs: project: maven # or gradle # subdirectories: moduleA moduleB #for subdirectories support, needs to be run with custom command ``` +
### For Gradle project @@ -71,8 +76,6 @@ The workflow, usually declared in `.github/workflows/publish-javadoc.yml`, looks
.github/workflows/publish-javadoc-gradle.yml - - ```YAML name: Deploy Javadoc @@ -94,14 +97,19 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} javadoc-branch: javadoc java-version: 17 - target-folder: javadoc + 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: +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 @@ -127,12 +135,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 . ``` +
+### 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 Don't forget to configure your repository settings with your new GitHub Page. 😉 @@ -143,11 +187,11 @@ Don't forget 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. - ![]() [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. ### Badge @@ -155,17 +199,22 @@ Not only that, but if you have README.md file in your javadoc branch, the access ```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 @@ -174,12 +223,14 @@ act workflow_dispatch -W .github/workflows/test-action-local.yml -P ubuntu-lates ``` ## Contributors - + ## Stars 🎇 If you like or use this project, please don't forget 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). diff --git a/action.yml b/action.yml index e55edb1..5356158 100644 --- a/action.yml +++ b/action.yml @@ -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 @@ -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" @@ -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 }} @@ -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 @@ -112,29 +103,18 @@ 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 }} @@ -142,3 +122,14 @@ runs: 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