documentation.yml

name: "Documentation"

on:
  pull_request:
    branches:
      - "*.x"
    paths:
      - .github/workflows/documentation.yml
      - docs/**
  push:
    branches:
      - "*.x"
    paths:
      - .github/workflows/documentation.yml
      - docs/**

jobs:
  validate-with-guides:
    name: "Validate documentation with phpDocumentor/guides"
    runs-on: "ubuntu-22.04"

    steps:
      - name: "Checkout code"
        uses: "actions/checkout@v4"

      - name: "Install PHP"
        uses: "shivammathur/setup-php@v2"
        with:
          coverage: "none"
          php-version: "8.3"

      - name: "Remove existing composer file"
        run: "rm composer.json"

      - name: "Require phpdocumentor/guides-cli"
        run: "composer require --dev phpdocumentor/guides-cli --no-update"

      - name: "Install dependencies with Composer"
        uses: "ramsey/composer-install@v2"
        with:
          dependency-versions: "highest"

      - name: "Add orphan metadata where needed"
        run: |
          printf '%s\n\n%s\n' ":orphan:" "$(cat docs/en/sidebar.rst)" > docs/en/sidebar.rst
          printf '%s\n\n%s\n' ":orphan:" "$(cat docs/en/reference/installation.rst)" > docs/en/reference/installation.rst

      - name: "Run guides-cli"
        run: "vendor/bin/guides -vvv --no-progress docs/en 2>&1 | grep -v 'No template found for rendering directive' | ( ! grep WARNING )"