brew/.github/workflows/docs.yml at main · Homebrew/brew · 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
136
137
138
139
140
141
name: Documentation

on:
  push:
    branches:
      - main
  pull_request:
  merge_group:

permissions:
  contents: read
  pages: read

env:
  HOMEBREW_DEVELOPER: 1
  HOMEBREW_NO_AUTO_UPDATE: 1
  HOMEBREW_NO_ENV_HINTS: 1
  HOMEBREW_NO_INSTALL_CLEANUP: 1

defaults:
  run:
    shell: bash -xeuo pipefail {0}

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Homebrew
        id: set-up-homebrew
        uses: Homebrew/actions/setup-homebrew@main
        with:
          core: false
          cask: false
          stable: false

      - name: Checkout repository
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          persist-credentials: false

      - name: Install Vale
        run: brew install vale

      - name: Cleanup Homebrew/brew docs
        if: github.repository == 'Homebrew/brew'
        run: |
          # No ignore support (https://github.com/errata-ai/vale/issues/131).
          rm -r Library/Homebrew/vendor

          # Generate latest manpage
          brew generate-man-completions --no-exit-code

      - name: Run Vale
        run: vale docs/

      - name: Setup Ruby
        uses: Homebrew/actions/setup-ruby@main
        with:
          bundler-cache: true
          portable-ruby: true
          working-directory: docs

      - name: Check Markdown syntax
        working-directory: docs
        run: bundle exec rake lint

      - name: Check code blocks conform to our Ruby style guide
        run: brew style docs

      - name: Generate formulae.brew.sh API samples
        if: github.repository == 'Homebrew/formulae.brew.sh'
        working-directory: docs
        run: ../script/generate-api-samples.rb --template

      - name: Cache HTML Proofer
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: tmp/.htmlproofer
          key: ${{ runner.os }}-htmlproofer

      - name: Build the site
        working-directory: docs
        run: bundle exec rake build

      - name: Check for broken links
        if: github.event_name == 'pull_request'
        working-directory: docs
        run: bundle exec rake test || bundle exec rake test

      - name: Rebuild the site with YARD
        if: github.repository == 'Homebrew/brew'
        working-directory: docs
        run: bundle exec rake yard build

      - name: Upload pages artifact
        if: github.repository == 'Homebrew/brew'
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: docs/_site/

  deploy:
    needs: docs
    if: ${{ github.repository == 'Homebrew/brew' && github.ref_name == 'main' }}
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    outputs:
      deploy_url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-slim
    timeout-minutes: 10
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

  deploy-issue:
    name: Open/close deploy issue
    needs: [docs, deploy]
    if: ${{ github.repository == 'Homebrew/brew' && always() && github.ref_name == 'main' }}
    env:
      RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
    runs-on: ubuntu-slim
    timeout-minutes: 5
    permissions:
      issues: write # for Homebrew/actions/create-or-update-issue
    steps:
      - name: Open, update, or close deploy issue
        uses: Homebrew/actions/create-or-update-issue@main
        with:
          token: ${{ github.token }}
          repository: ${{ github.repository }}
          title: docs.brew.sh deployment failed!
          body: The most recent [docs.brew.sh deployment failed](${{ env.RUN_URL }}).
          labels: deploy failure
          update-existing: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped') }}
          close-existing: ${{ needs.deploy.result == 'success' }}
          close-from-author: github-actions[bot]
          close-comment: The most recent [docs.brew.sh deployment succeeded](${{ env.RUN_URL }}). Closing issue.