CI: Add docbook-cs linting

.github/workflows/docbook-cs.yml

@@ -0,0 +1,100 @@
+# https://docs.github.com/en/actions
+
+name: "DocBook Lint"
+
+on:
+  push:
+    branches:
+      - "master"
+  pull_request:
+    branches:
+      - "master"
+
+permissions:
+  contents: "read"
+
+concurrency:
+  group: "${{ github.workflow }}-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  docbook-cs:
+    name: "DocBook Style Check"
+    runs-on: "ubuntu-latest"
+
+    strategy:
+      matrix:
+        language:
+          - "en"
+
+    steps:
+      - name: "Checkout php/doc-${{ matrix.language }}"
+        uses: "actions/checkout@v6"
+        with:
+          ref: "${{ github.event.pull_request.head.sha }}"
+          path: "${{ matrix.language }}"
+          fetch-depth: 50
+
+      - name: "Checkout php/doc-base"
+        uses: "actions/checkout@v6"
+        with:
+          path: "doc-base"
+          repository: "php/doc-base"
+
+      - name: "Checkout php/docbook-cs"
+        uses: "actions/checkout@v6"
+        with:
+          path: "docbook-cs"
+          repository: "php/docbook-cs"
+
+      - name: "Fetch base branch with merge-base"
+        working-directory: "${{ matrix.language }}"
+        run: |
+          git fetch origin ${{ github.base_ref }} --depth=50
+          # Deepen until we find the merge-base (handles long-lived PRs)
+          for i in 1 2 3 4 5; do
+            if git merge-base origin/${{ github.base_ref }} HEAD >/dev/null 2>&1; then
+              break
+            fi
+            git fetch --deepen=100 origin ${{ github.base_ref }}
+          done
+
+      - name: "Setup PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "8.5"
+          extensions: "dom, libxml, simplexml"
+          tools: composer, cs2pr
+
+      - name: "Build documentation"
+        run: |
+          php doc-base/configure.php \
+            --disable-libxml-check \
+            --enable-xml-details \
+            --redirect-stderr-to-stdout \
+            --with-lang=${{ matrix.language }}
+
+      - name: "Install docbook-cs"
+        working-directory: "docbook-cs"
+        run: composer install --no-interaction --no-progress
+
+      - name: "Run docbook-cs with diff"
+        working-directory: "${{ matrix.language }}"
+        run: |
+          set -o pipefail
+          git diff origin/${{ github.base_ref }}...HEAD | php ../docbook-cs/bin/docbook-cs \
+            --report=checkstyle \
+            --diff \
+            --no-colors > docbook-report.xml
+
+      - name: "Upload report"
+        if: ${{ ! cancelled() }}
+        uses: "actions/upload-artifact@v7"
+        with:
+          name: "docbook-report"
+          path: "${{ matrix.language }}/docbook-report.xml"
+
+      - name: "Annotate PR with violations"
+        if: ${{ ! cancelled() }}
+        working-directory: "${{ matrix.language }}"
+        run: cs2pr docbook-report.xml --colorize --prepend-filename

docbookcs.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<docbookcs xmlns="https://php.github.io/docbook-cs/config"
+           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xsi:schemaLocation="https://php.github.io/docbook-cs/config
+                               https://php.github.io/docbook-cs/config.xsd">
+
+ <project>
+  <directory alias="doc-en">en</directory>
+  <directory>doc-base</directory>
+ </project>
+
+ <sniffs>
+  <sniff class="DocbookCS\Sniff\SimparaSniff" />
+  <sniff class="DocbookCS\Sniff\ExceptionNameSniff" />
+  <sniff class="DocbookCS\Sniff\AttributeOrderSniff" />
+  <sniff class="DocbookCS\Sniff\WhitespaceSniff" />
+ </sniffs>
+
+ <paths>
+  <path>.</path>
+ </paths>
+
+ <entities>
+  <file>contributors.ent</file>
+  <file>extensions.ent</file>
+  <file>language-defs.ent</file>
+  <file>language-snippets.ent</file>
+  <directory>../doc-base/entities/</directory>
+  <file>../doc-base/temp/file-entities.ent</file>
+  <directory>../doc-base/temp/file-entities</directory>
+ </entities>
+
+ <exclude>
+  <pattern>output/*</pattern>
+ </exclude>
+
+</docbookcs>