Improve fetch external docs workflow (#1713)

Signed-off-by: jsetton <jeremy.setton@gmail.com>

.github/workflows/fetch_docs_openhab-alexa.yml

@@ -1,4 +1,4 @@
-name: Fetch OpenHAB Skill For Amazon Alexa Docs
+name: Fetch openHAB Skill For Amazon Alexa Docs
 
 on:
   # Repository dispatch event, to be triggerd by an openhab-alexa release
@@ -12,5 +12,7 @@ jobs:
     uses: openhab/openhab-docs/.github/workflows/fetch_external_docs_reusable.yml@main
     with:
       base_source_repository: openhab-alexa
+      base_source_ref: ${{ github.event.client_payload.ref }}
       base_folder: _addons_ios/alexa-skill
+      doc_base_file: USAGE.md
       has_images: true

.github/workflows/fetch_docs_openhab-android.yml

@@ -0,0 +1,20 @@
+name: Fetch openHAB Android Client Docs
+
+on:
+  # Repository dispatch event, to be triggerd by an openhab-alexa release
+  # or manually from the openhab-android repository
+  repository_dispatch:
+    types: [update-openhab-android-docs-event]
+  workflow_dispatch:
+
+jobs:
+  call-reusable-fetch-workflow:
+    uses: openhab/openhab-docs/.github/workflows/fetch_external_docs_reusable.yml@main
+    with:
+      base_source_repository: openhab-android
+      base_source_ref: ${{ github.event.client_payload.ref }}
+      base_folder: addons/uis/apps
+      base_file: android.md
+      doc_base_file: USAGE.md
+      has_images: true
+      is_self_contained: false

.github/workflows/fetch_docs_openhab-google-assistant.yml

@@ -0,0 +1,18 @@
+name: Fetch openHAB Google Assistant Docs
+
+on:
+  # Repository dispatch event, to be triggerd by an openhab-alexa release
+  # or manually from the openhab-google-assistant repository
+  repository_dispatch:
+    types: [update-openhab-google-assistant-docs-event]
+  workflow_dispatch:
+
+jobs:
+  call-reusable-fetch-workflow:
+    uses: openhab/openhab-docs/.github/workflows/fetch_external_docs_reusable.yml@main
+    with:
+      base_source_repository: openhab-google-assistant
+      base_source_ref: ${{ github.event.client_payload.ref }}
+      base_folder: _addons_ios/google-assistant
+      doc_base_file: USAGE.md
+      has_images: true

.github/workflows/fetch_docs_openhab-mycroft.yml

@@ -0,0 +1,18 @@
+name: Fetch openHAB Mycroft Skill Docs
+
+on:
+  # Repository dispatch event, to be triggerd by an openhab-alexa release
+  # or manually from the openhab-mycroft repository
+  repository_dispatch:
+    types: [update-openhab-mycroft-docs-event]
+  workflow_dispatch:
+
+jobs:
+  call-reusable-fetch-workflow:
+    uses: openhab/openhab-docs/.github/workflows/fetch_external_docs_reusable.yml@main
+    with:
+      base_source_repository: openhab-mycroft
+      base_source_ref: ${{ github.event.client_payload.ref }}
+      base_folder: _addons_ios/mycroft-skill
+      doc_base_dir: ''
+      doc_base_file: USAGE.md

.github/workflows/fetch_docs_openhabian.yml

@@ -12,7 +12,8 @@ jobs:
     uses: openhab/openhab-docs/.github/workflows/fetch_external_docs_reusable.yml@main
     with:
       base_source_repository: openhabian
+      base_source_ref: ${{ github.event.client_payload.ref }}
       base_folder: installation
       doc_base_name: openhabian
       has_images: true
-      image_base_name: openHABian
+      is_self_contained: false

.github/workflows/fetch_external_docs_reusable.yml

@@ -1,47 +1,65 @@
 name: Fetch Docs Reusable
-# Generic action for fetching doc contents
+# Generic action for fetching doc resources
 # This action is meant to be called by a detailled action for a specific repository, defining the needed parameters
 
 on:
   workflow_call:
     inputs:
       base_target_branch:
-        description: 'The branch to check out in the target repository. Defaults to `final-stable`.'
-        default: 'final-stable'
+        description: The branch to check out in the target repository. Defaults to `final-stable`.
+        default: final-stable
         required: false
         type: string
       base_source_organization:
-        description: 'The organization or user, that is holding the base repository. Defaults to `openhab`.'
-        default: 'openhab'
+        description: The organization or user that holds the base repository. Defaults to `openhab`.
+        default: openhab
         required: false
         type: string
       base_source_repository:
-        description: 'The repository that holds the source contents to copy.'
+        description: The repository that holds the source resources to copy.
         required: true
         type: string
-      base_source_branch:
-        description: 'The branch that contents should get copied. Defaults to `main`.'
-        default: 'main'
+      base_source_ref:
+        description: The branch or tag ref that holds the source resources to copy.
         required: false
         type: string
       base_folder:
-        description: 'The folder that is holding the contents in the target repository.'
+        description: The folder that holds the resources in the target repository.
         required: true
         type: string
+      base_file:
+        description: The default file name to rename as if `doc_base_file` defined. Defaults to `readme.md`.
+        default: readme.md
+        required: false
+        type: string
       doc_base_name:
-        description: 'The doc file name prefix for lookup options.'
+        description: The doc file name prefix for lookup options.
+        required: false
+        type: string
+      doc_base_dir:
+        description: The doc directory path that holds the source resources to copy. Defaults to `/docs`.
+        default: /docs
+        required: false
+        type: string
+      doc_base_file:
+        description: The doc default file to rename as `base_file`.
+        required: false
+        type: string
+      image_base_dir:
+        description: The image directory path that holds the image resources. Defaults to `/images`.
+        default: /images
         required: false
         type: string
       has_images:
-        description: 'Flag for enabling image copy commands.'
+        description: If doc has images. Defaults to `false`.
         default: false
         required: false
         type: boolean
-      image_base_name:
-        description: 'The image name prefix for lookup options'
-        default: ""
+      is_self_contained:
+        description: If doc is self-contained. Defaults to `true`.
+        default: true
         required: false
-        type: string
+        type: boolean
 
 jobs:
   fetchDocs:
@@ -51,51 +69,56 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v2.4.0
         with:
-          ref: ${{inputs.base_target_branch}}
+          ref: ${{ inputs.base_target_branch }}
 
       - name: Checkout external repository
         uses: actions/checkout@v2.4.0
         with:
-          repository: ${{inputs.base_source_organization}}/${{inputs.base_source_repository}}
-          path: './external_contents/${{inputs.base_source_repository}}'
+          repository: ${{ inputs.base_source_organization }}/${{ inputs.base_source_repository }}
+          path: ./external_repositories/${{ inputs.base_source_repository }}
+          ref: ${{ inputs.base_source_ref }}
 
-      - name: Remove existing doc contents
-        run: find ${{inputs.base_folder}} -iname "${{inputs.doc_base_name}}*" -type f -delete
+      - name: Initialize doc folder structure
+        run: mkdir -vp "${{ inputs.base_folder }}${{ inputs.has_images && inputs.image_base_dir || '' }}"
 
-      - name: Copy newest doc contents
-        run: |
-          echo "Copy current doc contents"
-          cp -v ./external_contents/${{inputs.base_source_repository}}/docs/${{inputs.doc_base_name}}*.md ${{inputs.base_folder}}
+      # Remove existing doc resources if self-contained or doc file name prefix defined
+      - name: Remove existing doc resources
+        if: ${{ inputs.is_self_contained || inputs.doc_base_name }}
+        run: find $TARGET_DIR -iname "${{ inputs.doc_base_name }}*" -type f -exec rm -v {} \;
+        env:
+          TARGET_DIR: ${{ inputs.base_folder }}
 
-          if [ -f USAGE.md ]; then
-            mv USAGE.md readme.md
-          fi 
+      - name: Copy latest doc resources
+        run: find $SOURCE_DIR -maxdepth 1 -iname "${{ inputs.doc_base_name }}*.md" -type f -exec cp -v {} $TARGET_DIR \;
+        env:
+          SOURCE_DIR: ./external_repositories/${{ inputs.base_source_repository }}${{ inputs.doc_base_dir }}
+          TARGET_DIR: ${{ inputs.base_folder }}
 
-      # Copy images only if flag is set to true 
-      - name: Copy newest images
-        if: ${{ inputs.has_images == true }}
-        run: |
-          echo "Copy current images"
-          cp -v ./external_contents/${{inputs.base_source_repository}}/docs/images/${{inputs.image_base_name}}* ${{inputs.base_folder}}/images
+      # Rename doc default file if parameter defined
+      - name: Rename doc default file
+        if: ${{ inputs.doc_base_file }}
+        run: mv -v ${{ inputs.doc_base_file }} ${{ inputs.base_file }}
+        working-directory: ${{ inputs.base_folder }}
 
-      - name: Remove external repositories
-        run: rm -rf ./external_contents
+      # Copy image resources if has images
+      - name: Copy latest image resources
+        if: ${{ inputs.has_images }}
+        run: find $SOURCE_DIR -maxdepth 1 -iname "${{ inputs.doc_base_name }}*.png" -type f -exec cp -v {} $TARGET_DIR \;
+        env:
+          SOURCE_DIR: ./external_repositories/${{ inputs.base_source_repository }}${{ inputs.doc_base_dir }}${{ inputs.image_base_dir }}
+          TARGET_DIR: ${{ inputs.base_folder }}${{ inputs.image_base_dir }}
+
+      - name: Remove external repository files
+        run: rm -rf ./external_repositories
 
       # Create an automated pull request, if the resulting branch is ahead of the `base-target-branch`
-      - name: Create Pull Request
-        id: cpr
+      - name: Create pull request
         uses: peter-evans/create-pull-request@v3
         with:
-          commit-message: Automated ${{inputs.base_source_repository}} Docs fetch
+          commit-message: Automated ${{ inputs.base_source_repository }} Docs fetch
           committer: openHAB Bot <info@openhab.org>
           author: openHAB Bot <info@openhab.org>
-          branch: automated/fetch_${{inputs.base_source_repository}}_docs
+          branch: automated/fetch_${{ inputs.base_source_repository }}_docs
           delete-branch: true
-          title: "[Automated] Fetch ${{inputs.base_source_repository}} docs"
-          labels: |
-            automated_pr
-
-      - name: Check outputs
-        run: |
-          echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
-          echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}"
+          title: "[Automated] Fetch ${{ inputs.base_source_repository }} docs"
+          labels: automated_pr