Propogate error when docsbuild fails, add docs build to CI. (#1852)

* Fix CI case where no projects are modified.

`if args.dirty_projects:` was evaluating to false when the project list was empty.
Explicitly check for `None` instead.

* Propogate error when docsbuild fails.

* Fix rst syntax.

/home/runner/work/cccl/cccl/docs/libcudacxx/extended_api/math.rst:22: ERROR: Unknown target name: "blocks".

* Build docs in PR CI.

* Remove dead code.

.github/actions/docs-build/action.yml

@@ -0,0 +1,51 @@
+name: "CCCL Docs Build/Upload"
+description: "Builds the docs and uploads them as workflow and pages artifacts."
+
+inputs:
+  upload_workflow_artifact:
+    description: "Uploads the built docs as a workflow artifact (actions/upload-artifact)."
+    required: false
+    default: "true"
+  upload_pages_artifact:
+    description: "Uploads the built docs as a workflow artifact (actions/upload-pages-artifact). Required for docs-deploy action."
+    required: false
+    default: "true"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Setup Pages
+      uses: actions/configure-pages@v3
+
+    # Build all docs
+    - name: Build all docs
+      shell: bash --noprofile --norc -euo pipefail {0}
+      run: ./docs/gen_docs.bash
+
+    # Copy all docs to the right folder
+    - name: Move docs to right folder
+      shell: bash --noprofile --norc -euo pipefail {0}
+      run: |
+        mkdir _site
+        cp -rf ./docs/_build/docs/cccl/latest/* _site
+        mkdir _site/cub
+        cp -rf ./docs/_build/docs/cub/latest/* _site/cub
+        mkdir _site/libcudacxx
+        cp -rf ./docs/_build/docs/libcudacxx/latest/* _site/libcudacxx
+        mkdir _site/thrust
+        cp -rf ./docs/_build/docs/thrust/latest/* _site/thrust
+        ./docs/scrape_docs.bash ./_site
+
+    # Update docs as workflow artifact:
+    - name: Upload artifact
+      if: ${{ inputs.upload_workflow_artifact == 'true' }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: docs
+        path: _site/
+        compression-level: 0
+
+    # Upload docs as pages artifacts
+    - name: Upload artifact
+      if: ${{ inputs.upload_pages_artifact == 'true' }}
+      uses: actions/upload-pages-artifact@v3

.github/actions/workflow-build/action.yml

@@ -58,8 +58,8 @@ runs:
       env:
         allow_override: ${{ inputs.allow_override == 'true' && '--allow-override' || ''}}
         skip_tests: ${{ inputs.skip_tests == 'true' && '--skip-tests' || ''}}
-        dirty_projects_flag: ${{ steps.inspect-changes.outputs.dirty_projects != '' && '--dirty-projects' || ''}}
-        dirty_projects: ${{ steps.inspect-changes.outputs.dirty_projects }}
+        dirty_projects_flag: ${{ inputs.inspect_changes_script != '' && '--dirty-projects' || ''}}
+        dirty_projects: ${{ inputs.inspect_changes_script != '' && steps.inspect-changes.outputs.dirty_projects || ''}}
         matrix_parser: ${{ inputs.matrix_parser && inputs.matrix_parser || '${GITHUB_ACTION_PATH}/build-workflow.py' }}
       run: |
         echo "Parsing matrix file into a workflow..."

.github/actions/workflow-build/build-workflow.py

@@ -788,7 +788,7 @@ def parse_workflow_matrix_jobs(args, workflow_name):
     if args:
         if args.skip_tests:
             matrix_jobs = remove_skip_test_jobs(matrix_jobs)
-        if args.dirty_projects:
+        if args.dirty_projects != None:  # Explicitly check for None, as an empty list is valid:
             matrix_jobs = [job for job in matrix_jobs if job['project'] in args.dirty_projects]
 
     # Don't remove excluded jobs if we're currently parsing them:

.github/workflows/build-docs.yml

@@ -29,31 +29,11 @@ jobs:
         uses: actions/checkout@v4
         with:
           persist-credentials: false
-      - name: Setup Pages
-        uses: actions/configure-pages@v3
-
-      # Build all docs
-      - name: Build all docs
-        run: ./docs/gen_docs.bash
-
-      # Copy all docs to the right folder
-      - name: Move docs to right folder
-
-        run: |
-          mkdir _site
-          cp -rf ./docs/_build/docs/cccl/latest/* _site
-          mkdir _site/cub
-          cp -rf ./docs/_build/docs/cub/latest/* _site/cub
-          mkdir _site/libcudacxx
-          cp -rf ./docs/_build/docs/libcudacxx/latest/* _site/libcudacxx
-          mkdir _site/thrust
-          cp -rf ./docs/_build/docs/thrust/latest/* _site/thrust
-          ./docs/scrape_docs.bash ./_site
-          cp ./docs/404.html _site/404.html
-
-      # Upload build artifacts
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v2
+      - name: Build and upload docs
+        uses: ./.github/actions/docs-build
+        with:
+          upload_workflow_artifact: "true"
+          upload_pages_artifact: "true"
 
   # Deployment job
   deploy:

.github/workflows/ci-workflow-pull-request.yml

@@ -160,6 +160,23 @@ jobs:
       contents: read
     uses: ./.github/workflows/verify-devcontainers.yml
 
+  verify-docs:
+    name: Build and Verify Docs
+    if: ${{ !contains(github.event.head_commit.message, '[skip-docs]') }}
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Build and upload docs
+        uses: ./.github/actions/docs-build
+        with:
+          upload_workflow_artifact: "true"
+          upload_pages_artifact: "false"
+
   # Check all other job statuses. This job gates branch protection checks.
   ci:
     name: CI
@@ -171,6 +188,7 @@ jobs:
     needs:
       - verify-workflow
       - verify-devcontainers
+      - verify-docs
     runs-on: ubuntu-latest
     steps:
       - name: Check results
@@ -192,6 +210,7 @@ jobs:
 
           check_result "verify-workflow"      "success" "${{needs.verify-workflow.result}}"
           check_result "verify-devcontainers" "success" "${{needs.verify-devcontainers.result}}"
+          check_result "verify-docs"          "success" "${{needs.verify-docs.result}}"
 
           if [[ "$status" != "success" ]]; then
             exit 1

docs/gen_docs.bash

@@ -36,4 +36,7 @@ if [ ! -n "$(find img -name '*.png')" ]; then
     done
 fi
 
-./repo.sh docs || echo "!!! There were errors while generating"
+if ! ./repo.sh docs; then
+    echo "!!! There were errors while generating"
+    exit 1
+fi

docs/libcudacxx/extended_api/math.rst

@@ -19,7 +19,7 @@ ceil_div
 
    The function is only constexpr from C++14 onwards
 
-**Example**: This API is very useful for determining the _number of thread blocks_ required to process a fixed amount of work, given a fixed number of threads per block:
+**Example**: This API is very useful for determining the *number of thread blocks* required to process a fixed amount of work, given a fixed number of threads per block:
 
 .. code:: cuda