ci-documentation.yml

#
# Licensed under the Apache License v2.0 with LLVM Exceptions.
# See https://llvm.org/LICENSE.txt for license information.
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
#
# Copyright (c) 2026 Alan de Freitas (alandefreitas@gmail.com)
#
# Official repository: https://github.com/cppalliance/mrdocs
#
# Per-OS validation that the docs/website/Antora-UI pipelines build
# cleanly with the installed mrdocs binary. Scope-gated: runs when
# source, docs, build, or third-party files changed (i.e. anything
# that can influence rendered documentation). Skipped on tooling /
# ci / toolchain-only PRs.

name: Documentation

on:
  workflow_call:
    inputs:
      submatrix:
        description: 'JSON-encoded releases submatrix from cpp-matrix'
        type: string
        required: true
      use-develop-binaries:
        description: 'true to fetch packages from develop-release instead of this run'
        type: boolean
        default: false

jobs:
  documentation:
    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJSON(inputs.submatrix) }}

    defaults:
      run:
        shell: bash

    name: ${{ matrix.os }}
    runs-on: ${{ matrix.runs-on }}
    container: ${{ matrix.container }}
    permissions:
      contents: read
    steps:
      - name: Container Bootstrap
        uses: alandefreitas/cpp-actions/container-bootstrap@v1.9.5

      - name: Install packages
        uses: alandefreitas/cpp-actions/package-install@v1.9.5
        with:
          apt-get: build-essential asciidoctor cmake bzip2 git rsync

      - name: Clone MrDocs
        uses: actions/checkout@v6
        with:
          fetch-depth: 1

      - name: Install Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '20'

      - name: Setup C++
        uses: alandefreitas/cpp-actions/setup-cpp@v1.9.5
        id: setup-cpp
        with:
          compiler: ${{ matrix.compiler }}
          version: ${{ matrix.version }}

      # Same dual-source pattern as ci-releases.yml: fresh-build artifact
      # when we built this run, develop-release fallback otherwise.
      - name: Download MrDocs package (fresh build)
        if: ${{ !inputs.use-develop-binaries }}
        uses: actions/download-artifact@v8
        with:
          name: ${{ matrix.mrdocs-release-package-artifact }}
          path: packages

      - name: Download MrDocs package (develop-release fallback)
        if: ${{ inputs.use-develop-binaries }}
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
          mkdir -p packages
          case "${{ runner.os }}" in
            Linux)   pattern='*Linux*' ;;
            Windows) pattern='*Windows*' ;;
            macOS)   pattern='*Darwin*' ;;
            *) echo "::error::unknown runner.os: ${{ runner.os }}"; exit 1 ;;
          esac
          gh release download develop-release --pattern "$pattern" -D packages

      - name: Install MrDocs from Package
        run: .github/scripts/install-mrdocs-package.sh

      - name: Generate Landing Page
        working-directory: docs/website
        run: |
          npm ci
          node render.js
          mkdir -p ../../build/website
          cp index.html ../../build/website/index.html
          cp robots.txt ../../build/website/robots.txt
          cp styles.css ../../build/website/styles.css
          cp -r assets ../../build/website/assets

      - name: Generate Antora UI
        working-directory: docs/ui
        run: |
          GH_TOKEN="${{ secrets.GITHUB_TOKEN }}"
          export GH_TOKEN
          npm ci
          npx gulp lint
          npx gulp

      - name: Generate Local Documentation
        working-directory: docs
        run: |
          GH_TOKEN="${{ secrets.GITHUB_TOKEN }}"
          export GH_TOKEN
          set -x
          npm ci
          npx antora antora-playbook.yml --attribute branchesarray=HEAD --stacktrace --log-level=debug
          mkdir -p ../build/docs-local
          cp -vr build/site/* ../build/docs-local

      - name: Upload Website as Artifact
        uses: actions/upload-artifact@v7
        with:
          name: Website ${{ runner.os }}
          path: build/website
          retention-days: 30