feat/javadoc: automate Javadoc deployment via gh-pages

.github/workflows/automate_javadoc.yml

@@ -1,27 +1,29 @@
-# SPDX-FileCopyrightText: 2022 RTE FRANCE
+# SPDX-FileCopyrightText: 2022 2023 RTE FRANCE
 #
 # SPDX-License-Identifier: Apache-2.0
 name: Continuous Deployment - JavaDocs
 
 on:
-  push:
-    branches:
-      - 'feat/javadoc'
+  pull_request_target:
+    types: [ labeled, closed ]
+
 jobs:
   build:
+    if: ${{  github.event.pull_request.base.ref == 'develop' && github.actor != 'dependabot[bot]' && github.event.pull_request.merged && contains(github.event.pull_request.labels.*.name, 'javadoc') }}
     name: Java Docs
     runs-on: ubuntu-latest
     env:
-      from_branch: feat/javadoc
-      target_branch: feat/117_Documentation_SCD_Generation_Process
+      DEPLOYMENT_BRANCH: gh-pages
+      DEPENDABOT_BRANCH: dependabot/javadoc-${{ github.head_ref || github.ref_name }}-${{ github.event.pull_request.number }}
     steps:
-      # Use develop as base branch to generate javadoc
-      - name: Setup Environment
+      - name: Checkout
         uses: actions/checkout@v3
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v3
         with:
           distribution: 'zulu'
           java-version: '17'
-          ref: ${{ env.target_branch }}
 
       - name: Create custom Maven Settings.xml
         uses: whelk-io/maven-settings-xml-action@v21
@@ -33,6 +35,8 @@ jobs:
         run: |
           git config --global user.name '${{ secrets.CONFIG_CI_USER_NAME }}'
           git config --global user.email '${{ secrets.CONFIG_CI_USER_EMAIL }}'
+          git config pull.rebase false
+          git fetch origin ${{ env.DEPLOYMENT_BRANCH }}
 
       - name: Import GPG key
         id: import_gpg
@@ -42,27 +46,25 @@ jobs:
           git_user_signingkey: true
           git_commit_gpgsign: true
 
-      - name: Prepare Pull Request branch
+      # Take note that your GitHub Pages site is currently being built from the /docs folder in the DEPLOYMENT_BRANCH branch.
+      - name: Prepare Pull Request branch & commit files
         run: |
           mvn -s custom_maven_settings.xml clean javadoc:aggregate -P javadoc
           mkdir -p docs/javadoc
           yes | cp -Rf target/site/apidocs/* docs/javadoc/
-          git checkout -b ${{ env.from_branch }}-pull-request
+          git checkout -b temp
+          git add docs/javadoc/
+          git commit -m "[dependabot/javadoc/temp]: update javadoc"
+          git checkout ${{ env.DEPLOYMENT_BRANCH }}
+          git clean -fdx
+          git checkout -b ${{ env.DEPENDABOT_BRANCH }}
+          git cherry-pick -n -X theirs temp
+          git commit -m "[dependabot/javadoc]: update javadoc"
+          git checkout ${{ env.DEPLOYMENT_BRANCH }}
+          git merge ${{ env.DEPENDABOT_BRANCH }}
 
-      # Note that will fail if branch already exists.
       - name: Push Git Branch
         uses: ad-m/[email protected]
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          branch: ${{ env.from_branch }}-pull-request
-
-      # Note that will silently fail if PR already exists.
-      - name: Create Pull Request
-        uses: repo-sync/pull-request@v2
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          source_branch: ${{ env.from_branch }}-pull-request
-          destination_branch: ${{ env.target_branch }}
-          pr_title: "Docs: Update Java docs repository"
-          pr_body: "Automatically created from CI workflow"
-          pr_label: "documentation,javadoc"
+          branch: ${{ env.DEPLOYMENT_BRANCH }}

pom.xml

@@ -218,7 +218,6 @@
                         <configuration>
                             <doctitle>${javadoc.title}</doctitle>
                             <doclint>${javadoc.lint}</doclint>
-                            <additionalJOption>--no-module-directories</additionalJOption>
                         </configuration>
                     </plugin>
                 </plugins>

sct-app/src/main/java/org/lfenergy/compas/sct/app/package-info.java

@@ -3,6 +3,6 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- * <h3>sct-app is a group of automation services</h3>
+ * <h2>sct-app is a group of automation services</h2>
  */
 package org.lfenergy.compas.sct.app;

sct-commons/src/main/java/org/lfenergy/compas/sct/commons/dto/package-info.java

@@ -3,8 +3,8 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- *  <h3>sct.commons.dto is a group of DTO utils for operating on
+ *  <h2>sct.commons.dto is a group of DTO utils for operating on
  *      {@link org.lfenergy.compas.scl2007b4.model.SCL SCL} services
- *  </h3>
+ *  </h2>
  */
 package org.lfenergy.compas.sct.commons.dto;

sct-commons/src/main/java/org/lfenergy/compas/sct/commons/scl/com/package-info.java

@@ -3,9 +3,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- * <h3>scl.com is a group of services for operating on
+ * <h2>scl.com is a group of services for operating on
  *  {@link org.lfenergy.compas.scl2007b4.model.TCommunication Communication} object
- * </h3>
+ * </h2>
  * @see org.lfenergy.compas.scl2007b4.model.TCommunication
  * @see org.lfenergy.compas.scl2007b4.model.TSubNetwork
  * @see org.lfenergy.compas.scl2007b4.model.TConnectedAP

sct-commons/src/main/java/org/lfenergy/compas/sct/commons/scl/dtt/package-info.java

@@ -3,9 +3,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- * <h3>scl.dtt is a group of services for operating on
+ * <h2>scl.dtt is a group of services for operating on
  *  {@link org.lfenergy.compas.scl2007b4.model.TDataTypeTemplates DataTypeTemplates} object
- *  </h3>
+ *  </h2>
  * @see org.lfenergy.compas.scl2007b4.model.TLNodeType
  * @see org.lfenergy.compas.scl2007b4.model.TDOType
  * @see org.lfenergy.compas.scl2007b4.model.TDAType

sct-commons/src/main/java/org/lfenergy/compas/sct/commons/scl/header/package-info.java

@@ -3,9 +3,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- * <h3>scl.header is a group of services for operating on
+ * <h2>scl.header is a group of services for operating on
  *  {@link org.lfenergy.compas.scl2007b4.model.THeader Header} object
- *  </h3>
+ *  </h2>
  * @see org.lfenergy.compas.scl2007b4.model.THeader
  * @see org.lfenergy.compas.scl2007b4.model.THitem
  * @see <a href="https://github.com/com-pas/compas-sct/issues/6" target="_blank">Issue !6</a>

sct-commons/src/main/java/org/lfenergy/compas/sct/commons/scl/ied/package-info.java

@@ -3,9 +3,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- * <h3>scl.ied is a group of services for operating on
+ * <h2>scl.ied is a group of services for operating on
  *  {@link org.lfenergy.compas.scl2007b4.model.TIED IED} object
- *  </h3>
+ *  </h2>
  * @see org.lfenergy.compas.scl2007b4.model.TAccessPoint
  * @see org.lfenergy.compas.scl2007b4.model.TServices
  * @see org.lfenergy.compas.scl2007b4.model.TLDevice

sct-commons/src/main/java/org/lfenergy/compas/sct/commons/scl/package-info.java

@@ -3,13 +3,13 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- * <h3>commons.scl is a group of services for operating on
+ * <h2>commons.scl is a group of services for operating on
  *      {@link org.lfenergy.compas.scl2007b4.model.THeader Header} ,
  *      {@link org.lfenergy.compas.scl2007b4.model.TSubstation Substation} ,
  *      {@link org.lfenergy.compas.scl2007b4.model.TCommunication Communication} ,
  *      {@link org.lfenergy.compas.scl2007b4.model.TIED IED} ,
  *      {@link org.lfenergy.compas.scl2007b4.model.TDataTypeTemplates DataTypeTemplates} objects
- *  </h3>
+ *  </h2>
  * @see org.lfenergy.compas.scl2007b4.model.SCL
  */
 package org.lfenergy.compas.sct.commons.scl;

sct-commons/src/main/java/org/lfenergy/compas/sct/commons/scl/sstation/package-info.java

@@ -2,9 +2,9 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 /**
- * <h3>scl.sstation is a group of services for operating on
+ * <h2>scl.sstation is a group of services for operating on
  *  {@link org.lfenergy.compas.scl2007b4.model.TSubstation Substation} object
- *  </h3>
+ *  </h2>
  * @see org.lfenergy.compas.scl2007b4.model.TVoltageLevel
  * @see org.lfenergy.compas.scl2007b4.model.TFunction
  * @see org.lfenergy.compas.scl2007b4.model.TBay