mrdocs/.github/workflows/ci-documentation.yml at develop · cppalliance/mrdocs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
#
# 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.4

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

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

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

      - name: Setup C++
        uses: alandefreitas/cpp-actions/setup-cpp@v1.9.4
        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@v4
        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@v4
        with:
          name: Website ${{ runner.os }}
          path: build/website
          retention-days: 30