docs-a11y.yml

on:
  workflow_call:
    inputs:
      upload_report:
        description: "If true, upload a workflow artifact containing a HTML accessibility report."
        required: false
        type: boolean
        default: true
      allow_pr_comment:
        description: "If true, allow a bot to comment a text accessibility report in the PR."
        required: false
        type: boolean
        default: true
      notebook_kernel:
        description: "If jupyter notebooks are included in the docs, specify the kernel name they expect, e.g. the package name"
        required: false
        type: string
      additional_mamba_args:
        description: "Any additional arguments to pass to micromamba when creating the python environment"
        required: false
        default: ""
        type: string
      py3version:
        description: "Minor version of Python version 3 to run the test on (e.g. `11` for python v3.11)"
        required: false
        type: string
        default: "11"

defaults:
  run:
    shell: bash -l {0}

jobs:
  docs-accessibility:
    runs-on: ubuntu-20.04
    steps:
    - uses: arup-group/actions-city-modelling-lab/.github/actions/create-mamba-env@main
      with:
        py3version: ${{ inputs.py3version }}
        env_name: docs
        additional_mamba_args: ${{ inputs.additional_mamba_args }}
        cache_mamba_env: "true"

    - name: install jupyter kernel
      if: inputs.notebook_kernel != ''
      run: python -m ipykernel install --user --name ${{ inputs.notebook_kernel }}

    - name: build docs
      run: mkdocs build

    - uses: actions/setup-node@v4
      with:
        node-version: 20

    - name: Install Pa11y
      run: npm install pa11y-ci pa11y-ci-reporter-html -g && npm list -g --depth=2

    - name: Run Pa11y and pipe all output to file
      id: run-pa11y
      run: find .docs/ -type f -name "index.html" -exec pa11y-ci {} 2>&1 + | tee pa11y-output.txt

    - id: artifact-upload-step
      uses: actions/upload-artifact@v4
      if: inputs.upload_report == true
      with:
        name: Pa11y accessibility report
        path: ./reports/pa11y/

    - id: artifact-html-true
      name: Pipe artifact link string to environment variable if uploading report
      if: inputs.upload_report == true && inputs.allow_pr_comment == true
      run: |
        echo "ARTIFACT_HTML=Full output: <${{ steps.artifact-upload-step.outputs.artifact-url }}>" >> "$GITHUB_ENV"

    - id: artifact-html-false
      name: Pipe empty string to environment variable if not uploading report
      if: inputs.upload_report == false && inputs.allow_pr_comment == true
      run: |
        echo "ARTIFACT_HTML=" >> "$GITHUB_ENV"

    - name: Pipe summary lines of Pa11y output to an environment variable.
      if: inputs.allow_pr_comment == true
      run: |
        {
          LINES=$(find .docs/ -type f -name "index.html" | wc -l)
          echo 'PA11Y_OUTPUT<<EOF'
          cat pa11y-output.txt | head -n $((LINES + 3))
          echo EOF
        } >> "$GITHUB_ENV"

    - name: Comment PR with execution number
      if: inputs.allow_pr_comment == true
      uses: thollander/actions-comment-pull-request@v3
      with:
        message: |
          ## Documentation accessibility test results (using Pa11y)
          ${{ env.ARTIFACT_HTML }}

          <details><summary>Click for summary</summary>

          ``` shell
          ${{ env.PA11Y_OUTPUT }}
          ```

          </details>

        pr-number: ${{ github.event.number }}
        comment-tag: execution