sailfishos-patches · nephros · Aug 2, 2023 · Jul 25, 2023 · Jul 25, 2023 · Jul 25, 2023
diff --git a/.github/workflows/gendoc-create-html_qt56.yml b/.github/workflows/gendoc-create-html_qt56.yml
@@ -5,6 +5,12 @@ on:
     types: [published]
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
+    inputs:
+      SOURCE_BRANCH:
+        description: 'Branch to use as source'
+        required: true
+        default: 'master'
+        type: string
 
 # Allow only one build run, skipping runs queued between the run in-progress and latest queued.
 # cancel in-progress runs
@@ -13,57 +19,77 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  ### Build the documentation files:
+  #     - check out the branch
+  #     - Use a docker image containing `qdoc` to generate the files
+  #     - upload the results so the deployment job can pick it up
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     env:
       SEGMENT_DOWNLOAD_TIMEOUT_MINS: 3
-      DOC_SOURCE_BRANCH: "master"
-      DOC_TARGET_BRANCH: "gh-pages"
-      DOC_TARGET_DIR: "doctarget"
+      # branch to compile from
+      DOC_SOURCE_BRANCH: ${{ inputs.SOURCE_BRANCH != '' && inputs.SOURCE_BRANCH || 'master' }}
     steps:
-    - name: Checkout Source
+    - name: Checkout Source (${{ env.DOC_SOURCE_BRANCH }})
       uses: actions/checkout@v3
       with:
         ref: ${{ env.DOC_SOURCE_BRANCH }}
-
-    - name: Build Docs
+    - name: Generate Docs
+      env:
+        # docker image to run qdoc etc. on
+        DOCKER_IMG:        "icsinc/qt5.6.1-x64:latest"
       run: |
-        docker run --rm -v $PWD:/share icsinc/qt5.6.1-x64:latest /bin/bash -xc "
+        mkdir -p out
+        docker run --rm -v $PWD:/share $DOCKER_IMG /bin/bash -xc "
+            echo 'debconf debconf/frontend select Noninteractive' | sudo debconf-set-selections;
+            sudo rm -f /etc/apt/sources.list.d/beineri-opt-qt561-trusty-trusty.list
             sudo apt-get -qq update;
-            sudo apt-get -qq install -y qdoc-qt5;
             sudo apt-get -qq install -y qtbase5-dev;
             sudo apt-get -qq install -y git-core;
-            qdoc --version;
             mkdir -p build ;
             cd build ;
             cp -r /share/* . ;
             mkdir -p doc/generated;
             git clone --depth 1 -b upgrade-4.5.0 https://github.com/sailfishos/sailfish-qdoc-template doc/qdoc/sailfish-qdoc-template;
             /bin/bash -c ./makedocs;
-            mkdir /share/out;
             cp -rv doc/generated/* /share/out/;
             "
-
-    - name: Checkout Target
-      uses: actions/checkout@v3
+    # The builder outputs its index files in several subdirectories.
+    # The web root has no index file, so GH Pages throws a 404 when browsing there.
+    # So, lets add an index.html file to the root which redirects where we want to go:
+    - name: Add redirect Page
+      env:
+        REDIRECTOR: |
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <title>Redirecting...</title>
+              <meta http-equiv="refresh" content="1; url='patchmanager'"/>
+            </head>
+            <body>
+              <p>You will be redirected to the Documentation pages soon.</p>
+              <p>If this does not happpen, <a href="patchmanager">please click here</a>.</p>
+            </body>
+          </html>
+      run: echo "${REDIRECTOR}" > out/index.html
+    # Upload artifact for deploying to pages:
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v1
       with:
-        # only check out the target path:
-        sparse-checkout: doc
-        ref: ${{ env.DOC_TARGET_BRANCH }}
-        path: ${{ env.DOC_TARGET_DIR }}
+        path: './out'
 
-    - name: Copy Docs
-      run: |
-        rm -rf $GITHUB_WORKSPACE/$DOC_TARGET_DIR/doc/generated/*
-        cp -rv out/* $GITHUB_WORKSPACE/$DOC_TARGET_DIR/doc/generated/
+  # Now deploy to GH Pages
+  deploy:
+    needs: build
+    runs-on: ubuntu-22.04
+    # Grant GITHUB_TOKEN the permissions required by deploy-pages action
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+    steps:
+    - name: Setup Pages
+      uses: actions/configure-pages@v3
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v2
 
-    # Add and commit the results to the target branch
-    - name: Add and Commit
-      uses: EndBug/add-and-commit@v9
-      with:
-        cwd: ${{ env.DOC_TARGET_DIR }}
-        add: '-A doc/generated'
-        author_name: 'Github Action Runner'
-        author_email: 'noreply@github.com'
-        fetch: false
-        message: "[Actions] Generated Documentation for ${{ github.ref_name }}"
diff --git a/makedocs b/makedocs
@@ -14,29 +14,31 @@
 # In order to enable building in newer Qt versions, changes in both the qdoc
 # config files as well as the code comments will be required.
 
-echo '####### $0 starting... #######'
+printf '####### %s starting... #######\n' $0
+### verify "build" environment
+printf '## Verifying build environment:\n'
 switched_dirs="false"
 if gitroot=$(git rev-parse --show-toplevel 2>/dev/null); then
-	echo found a git root at $gitroot, running from there...
-	pushd $gitroot 2>/dev/null || cd $gitroot
+	printf '## found a git root at %s, running from there...\n' "$gitroot"
+	pushd $gitroot >/dev/null || cd $gitroot
 	switched_dirs="true"
 else
-	echo this is not a git repo, assuming root is \$PWD
+	printf '## this is not a git repo, assuming root is %s\n' "$PWD"
 fi
 
 # this is searched relative to the qdocconf file!!
 export SAILFISH_INSTALL_DOCS=sailfish-qdoc-template/config
 
-### verify "build" environment
-echo Verifying build environment...
-qdoc --version
+qdocver=$(qdoc --version)
 if [ $? -ne 0 ]; then
-  echo ERROR: qdoc does not seem to work! Please check your qt5 installation
+  printf '## ERROR: qdoc does not seem to work! Please check your qt5 installation\n'
   exit 1
+else
+  printf '## QDoc is: %s\n' "$qdocver"
 fi
 if [ ! -e doc/qdoc/sailfish-qdoc-template ]; then
-  echo ERROR: sailfish-qdoc-template does not exist
-  echo You should "'git clone --depth 1 -b upgrade-4.5.0 https://github.com/sailfishos/sailfish-qdoc-template doc/qdoc/sailfish-qdoc-template'"
+  printf '## ERROR: sailfish-qdoc-template does not exist\n'
+  printf "## You should \'git clone --depth 1 -b upgrade-4.5.0 https://github.com/sailfishos/sailfish-qdoc-template doc/qdoc/sailfish-qdoc-template'\n"
   exit 1
 fi
 
@@ -53,13 +55,13 @@ if [ -z "$QT_INSTALL_DOCS" ]; then
 	fi
 fi
 
-echo Generating Docs...
+printf '## Generating Docs...\n'
 [ -d $OUT ] && rm -r $OUT
-qdoc --no-examples --outputdir $OUT --outputformat HTML --installdir $QMAKE_INSTALL_ROOT/doc doc/qdoc/master.qdocconf --single-exec  $@
-echo Generated Docs at "$OUT"
+qdoc --no-examples --outputdir $OUT --outputformat HTML --installdir $QMAKE_INSTALL_ROOT/doc doc/qdoc/master.qdocconf --single-exec $@
+printf '## End of Doc generation at "%s"\n' "$OUT"
 
-[ $switched_dirs = "true" ] && popd 2>/dev/null || cd -
+[ $switched_dirs = "true" ] && popd >/dev/null || cd -
 
-echo '####### $0 done. #######'
+printf '####### %s done. #######\n' $0
 # always exit 0 for CI runs:
 exit 0