CI: Factor doc build steps into an action

Unidata · Nov 5, 2021 · ec1c34a · ec1c34a
1 parent 4e5692b
commit ec1c34a
Show file tree

Hide file tree

Showing 5 changed files with 73 additions and 69 deletions.
diff --git a/.github/actions/build-docs/action.yml b/.github/actions/build-docs/action.yml
@@ -0,0 +1,61 @@
+name: 'Build Docs'
+description: 'Build docs, optionally running linkchecker, and upload builds as artifacts.'
+inputs:
+  run-linkchecker:
+    description: 'Whether the linkchecker should be run'
+    required: false
+    default: 'false'
+  upload-build:
+    description: 'Whether the build of the docs should be uploaded as an artifact.'
+    required: false
+    default: 'true'
+  key:
+    description: 'Key to use for artifacts'
+    required: false
+    default: ''
+outputs:
+  log_available:
+    description: 'Whether a log from the doc build is available'
+    value: ${{ steps.builddocs.outputs.log_available == 'true' || steps.linkchecker.outputs.log_available == 'true'}}
+runs:
+  using: composite
+  steps:
+    - name: Build docs
+      shell: bash -l {0}
+      id: builddocs
+      # set -e makes sure bash fails on the first failing command, which isn't the case due to
+      # starting with -l
+      run: |
+        set -e -o pipefail
+        export TEST_DATA_DIR=$GITHUB_WORKSPACE/staticdata
+        pushd docs
+        make overridecheck html O=-W 2>&1 | tee build-${{ matrix.python-version }}.log || (
+            echo '::set-output name=log_available::true' && false
+        )
+        popd
+
+    - name: Run link checker
+      id: linkchecker
+      # Running linkchecker separately so that we avoid problems with vendored LICENSE
+      # files in the build directory
+      if: ${{ inputs.run-linkchecker == 'true'}}
+      shell: bash -l {0}
+      run: |
+        set -e
+        pushd docs
+        find build/html/_static -name LICENSE.md -delete
+        make linkcheck || true
+        # Make the presence of the output file with content (which could have specific redirects)
+        # fail the build
+        [ ! -s build/linkcheck/output.txt ] || (cp build/linkcheck/output.txt linkchecker.log && echo '::set-output name=log_available::true' && false)
+        popd
+
+    - name: Upload docs as artifact
+      if: ${{ inputs.upload-build == 'true' }}
+      uses: actions/upload-artifact@v2
+      with:
+        name: ${{ inputs.key }}-docs
+        path: |
+          docs/build/html
+          !docs/_static/*.pdf
+        retention-days: 5
diff --git a/.github/actions/run-tests/action.yml b/.github/actions/run-tests/action.yml
@@ -25,7 +25,7 @@ runs:
       shell: bash -l {0}
       # By running coverage in "parallel" mode and "combining", we can clean up the path names
       run: |
-        set -o pipefail
+        set -e -o pipefail
         export TEST_DATA_DIR=$GITHUB_WORKSPACE/staticdata
         python -m coverage run -p -m pytest --mpl -W error::metpy.deprecation.MetpyDeprecationWarning tests/ 2>&1 | tee tests-${{ inputs.key }}.log || (
             echo '::set-output name=log_available::true' && false

diff --git a/.github/workflows/docs-conda.yml b/.github/workflows/docs-conda.yml
@@ -41,16 +41,6 @@ jobs:
         python-version: ${{ matrix.python-version }}
 
     - name: Build docs
-      run: |
-        export TEST_DATA_DIR=$GITHUB_WORKSPACE/staticdata
-        pushd docs
-        make overridecheck html O=-W
-        popd
-
-    - name: Upload docs as artifact
-      uses: actions/upload-artifact@v2
+      uses: ./.github/actions/build-docs
       with:
-        name: ${{ matrix.os }}-${{ matrix.python-version }}-docs
-        path: |
-          docs/build/html
-          !docs/_static/*.pdf
+        key: ${{ matrix.os }}-${{ matrix.python-version }}
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -58,30 +58,11 @@ jobs:
         python-version: ${{ matrix.dep-versions }}
 
     - name: Build docs
-      run: |
-        export TEST_DATA_DIR=$GITHUB_WORKSPACE/staticdata
-        pushd docs
-        make overridecheck html O=-W
-        popd
-
-    - name: Enable linkchecker for PRs
-      # Doing the linkchecker separately so that we avoid problems with vendored LICENSE
-      # files in the build directory
-      if: ${{ github.event_name == 'pull_request' && matrix.check-links == true }}
-      run: |
-        pushd docs
-        find build/html/_static -name LICENSE.md -delete
-        make linkcheck
-        popd
-
-    - name: Upload docs as artifact
-      if: ${{ github.event_name == 'pull_request' }}
-      uses: actions/upload-artifact@v2
+      uses: ./.github/actions/build-docs
       with:
-        name: ${{ matrix.python-version }}-${{ matrix.dep-versions }}-docs
-        path: |
-          docs/build/html
-          !docs/_static/*.pdf
+        run-linkchecker: ${{ github.event_name == 'pull_request' && matrix.check-links == true }}
+        upload-build: ${{ github.event_name == 'pull_request' }}
+        key: ${{ runner.os }}-${{ matrix.python-version }}
 
     # This overrides the version "dev" with the proper version if we're building off a
     # branch that's not main (which is confined to n.nn.x above) or on a tag.

diff --git a/.github/workflows/nightly-builds.yml b/.github/workflows/nightly-builds.yml
@@ -93,31 +93,13 @@ jobs:
 
     - name: Build docs
       id: build
-      run: |
-        set -o pipefail
-        export TEST_DATA_DIR=$GITHUB_WORKSPACE/staticdata
-        pushd docs
-        make overridecheck html O=-W |& tee build-${{ matrix.python-version }}.log || (
-            echo '::set-output name=LOG_AVAILABLE::true' && false
-        )
-        popd
-
-    - name: Enable link checker
-      # Running linkchecker separately so that we avoid problems with vendored LICENSE
-      # files in the build directory
-      if: always()
-      run: |
-        pushd docs
-        find build/html/_static -name LICENSE.md -delete
-        make linkcheck
-        # Make the presence of the output file with content (which could have specific redirects)
-        # fail the build
-        [ ! -s build/linkchecker/output.txt ] || (echo '::set-output name=LOG_AVAILABLE::true' && false)
-        [ -s build/linkchecker/output.txt ] && cp build/linkchecker/output.txt linkchecker.log
-        popd
+      uses: ./.github/actions/build-docs
+      with:
+        run-linkchecker: true
+        key: ${{ matrix.python-version }}-nightly
 
     - name: Upload build log
-      if: ${{ always() && steps.build.outputs.LOG_AVAILABLE  == 'true' }}
+      if: ${{ always() && steps.build.outputs.log_available  == 'true' }}
       uses: actions/upload-artifact@v2
       with:
         name: log-nightly-docs-${{ matrix.python-version }}
@@ -126,16 +108,6 @@ jobs:
           docs/linkchecker.log
         retention-days: 5
 
-    - name: Upload docs as artifact
-      if: ${{ github.event_name == 'pull_request' }}
-      uses: actions/upload-artifact@v2
-      with:
-        name: ${{ matrix.python-version }}-nightly-docs
-        path: |
-          docs/build/html
-          !docs/_static/*.pdf
-        retention-days: 5
-
   Report:
     name: Report
     needs: [Tests, Docs]