documentation-checks.yaml

name: Automatic documentation checks

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
  workflow_call:
    inputs:
      python-version:
        description: 'Version of the Python interpreter to use (defaults to 3.10)'
        required: false
        type: string
        default: '3.10'
      makefile:
        description: 'Name of the Makefile to use (default: "Makefile.sp" if it exists, "Makefile" otherwise)'
        required: false
        type: string
        default: 'use-default'
      install-target:
        description: 'Target to run to install the tools (default: "install")'
        required: false
        type: string
        default: 'install'
      spelling-target:
        description: 'Target to run for the spelling check (default: "spelling")'
        required: false
        type: string
        default: 'spelling'
      woke-target:
        description: 'Target to run for the inclusive language check (default: "woke")'
        required: false
        type: string
        default: 'woke'
      linkcheck-target:
        description: 'Target to run for the link check (default: "linkcheck")'
        required: false
        type: string
        default: 'linkcheck'
      pa11y-target:
        description: 'Target to run for the accessibility check (default: "pa11y")'
        required: false
        type: string
        default: 'pa11y'
    outputs:
      spellcheck-result:
        description: "Result of the spelling check"
        value: ${{ jobs.docchecks.outputs.result_spelling }}
      woke-result:
        description: "Result of the inclusive language check"
        value: ${{ jobs.docchecks.outputs.result_woke }}
      linkcheck-result:
        description: "Result of the link check"
        value: ${{ jobs.docchecks.outputs.result_links }}
      pa11y-result:
          description: "Result of the pa11y check"
          value: ${{ jobs.docchecks.outputs.result_pa11y }}

jobs:
  docchecks:
    name: Run documentation checks
    runs-on: ubuntu-22.04
    outputs:
      result_spelling: ${{ steps.spellcheck-step.outcome }}
      result_woke: ${{ steps.woke-step.outcome }}
      result_links: ${{ steps.linkcheck-step.outcome }}
      result_pa11y: ${{ steps.pa11y-step.outcome }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ inputs.python-version }}

      - name: Spell Check
        id: spellcheck-step
        if: success() || failure()
        uses: canonical/documentation-workflows/spellcheck@main
        with:
          working-directory: doc/sphinx
          install-target: ${{ inputs.install-target }}
          spelling-target: ${{ inputs.spelling-target }}
          makefile: ${{ inputs.makefile }}

      - if: ${{ failure() && runner.debug }}
        name: Setup upterm session
        uses: mxschmitt/action-tmate@v3
        with:
          limit-access-to-actor: true