superduck/.github/workflows/docs.yml at main · Postroggy/superduck · 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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
name: Generate API Docs

# Automatically generate API reference docs:
#   - chrome-crx (TypeScript) via TypeDoc
#   - chrome-native-host (Go) via `go doc` snapshots
#
# On `main` pushes, the rendered TypeDoc site is published to GitHub Pages so
# `https://<org>.github.io/<repo>/` always reflects the latest extension API.
# On PRs the docs are only built (no publish) to catch broken JSDoc / unresolved
# symbols early.

on:
  push:
    branches: [main]
    paths:
      - 'chrome-crx/src/**'
      - 'chrome-crx/typedoc.json'
      - 'chrome-crx/package.json'
      - 'chrome-crx/tsconfig.json'
      - 'chrome-native-host/**/*.go'
      - 'chrome-native-host/go.mod'
      - 'site/index.html'
      - '.github/workflows/docs.yml'
  pull_request:
    paths:
      - 'chrome-crx/src/**'
      - 'chrome-crx/typedoc.json'
      - 'chrome-crx/package.json'
      - 'chrome-crx/tsconfig.json'
      - 'chrome-native-host/**/*.go'
      - 'chrome-native-host/go.mod'
      - 'site/index.html'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: pages-${{ github.ref }}
  cancel-in-progress: false

jobs:
  typedoc:
    name: TypeDoc (chrome-crx)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - name: Install chrome-crx deps
        working-directory: chrome-crx
        run: bun install --frozen-lockfile

      - name: Generate TypeDoc site
        working-directory: chrome-crx
        run: bun run docs

      - name: Upload TypeDoc artifact
        uses: actions/upload-artifact@v7
        with:
          name: typedoc-site
          path: chrome-crx/docs/api
          retention-days: 14

  godoc:
    name: go doc snapshots (chrome-native-host)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Go
        uses: actions/setup-go@v6
        with:
          go-version-file: chrome-native-host/go.mod

      - name: Render package docs to text
        working-directory: chrome-native-host
        run: |
          set -euo pipefail
          mkdir -p ../docs-build/godoc
          # Iterate over every Go package and snapshot its public API into a
          # plain-text file. This produces a deterministic, reviewable record
          # of the exported surface that an agent can grep through.
          go list ./... | while read -r pkg; do
            safe=$(echo "$pkg" | tr '/' '_')
            echo "==> $pkg"
            (echo "# $pkg"; echo; go doc -all "$pkg") > "../docs-build/godoc/${safe}.txt"
          done
          ls -la ../docs-build/godoc

      - name: Upload godoc artifact
        uses: actions/upload-artifact@v7
        with:
          name: godoc-snapshots
          path: docs-build/godoc
          retention-days: 14

  publish-pages:
    name: Publish docs to GitHub Pages
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: [typedoc, godoc]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}
    steps:
      - uses: actions/checkout@v6

      - name: Download TypeDoc artifact
        uses: actions/download-artifact@v8
        with:
          name: typedoc-site
          path: site/typedoc

      - name: Download godoc artifact
        uses: actions/download-artifact@v8
        with:
          name: godoc-snapshots
          path: site/godoc

      - name: Generate godoc index.html
        run: |
          cd site/godoc
          {
            echo '<!doctype html><html lang="en"><head><meta charset="utf-8"><title>godoc snapshots</title>'
            echo '<style>body{font-family:-apple-system,system-ui,sans-serif;max-width:720px;margin:4rem auto;padding:0 1rem;line-height:1.5}</style>'
            echo '</head><body><h1>chrome-native-host godoc snapshots</h1><ul>'
            for f in *.txt; do
              [ -f "$f" ] || continue
              printf '<li><a href="%s">%s</a></li>\n' "$f" "$f"
            done
            echo '</ul></body></html>'
          } > index.html

      - name: Verify landing page exists
        run: test -f site/index.html && echo "Landing page OK" || { echo "::error::site/index.html missing"; exit 1; }

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

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: site

      - name: Deploy to GitHub Pages
        id: deploy
        uses: actions/deploy-pages@v5