PyWry/.github/workflows/docs.yml at develop · deeleeramone/PyWry · 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
name: Deploy Documentation

on:
  push:
    branches:
      - main
  pull_request:
    branches: [main, develop]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: docs-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  detect-doc-impact:
    name: Detect docs impact
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      should-build: ${{ steps.detect.outputs.should-build }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - name: Decide whether docs build is required
        id: detect
        shell: bash
        env:
          IS_PR: ${{ github.event_name == 'pull_request' }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          set -euo pipefail

          if [[ "$IS_PR" != "true" ]]; then
            echo "should-build=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          git fetch --depth=1 origin "$BASE_SHA"

          CHANGED=$(git diff --name-only "$BASE_SHA" HEAD)
          DOC_RELATED=$(echo "$CHANGED" | grep -E '^(pywry/docs/|pywry/.*\.py$|\.github/workflows/docs\.yml$)' || true)

          if [[ -n "$DOC_RELATED" ]]; then
            echo "should-build=true" >> "$GITHUB_OUTPUT"
          else
            echo "should-build=false" >> "$GITHUB_OUTPUT"
          fi

  build:
    if: github.event_name != 'pull_request' || needs.detect-doc-impact.outputs.should-build == 'true'
    needs: detect-doc-impact
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: |
          pip install mkdocs-material
          pip install -r pywry/docs/requirements.txt

      - name: Build docs
        run: |
          cd pywry/docs
          mkdocs build --strict

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: pywry/docs/site

  deploy:
    if: github.event_name != 'pull_request'
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    permissions:
      contents: read
      pages: write
      id-token: write
    concurrency:
      group: pages
      cancel-in-progress: false
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

  docs-required:
    name: Docs Required
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request' && always()
    needs:
      - detect-doc-impact
      - build
    permissions:
      contents: read
    steps:
      - name: Enforce required docs outcomes
        shell: bash
        env:
          SHOULD_BUILD: ${{ needs.detect-doc-impact.outputs.should-build }}
          BUILD_RESULT: ${{ needs.build.result }}
        run: |
          set -euo pipefail

          if [[ "$SHOULD_BUILD" == "false" ]]; then
            echo "No docs-impacting changes detected; docs build intentionally skipped."
            exit 0
          fi

          if [[ "$BUILD_RESULT" != "success" ]]; then
            echo "Docs build did not succeed (result: $BUILD_RESULT)"
            exit 1
          fi

          echo "Docs validation passed."