eb-stack/.github/workflows/ci_docs.yml at main · stackhands/eb-stack · 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
name: Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

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

jobs:
  build:
    name: Build Sphinx docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: prefix-dev/setup-pixi@v0.11.2
        with:
          cache: true
          cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
          environments: docs

      - uses: dtolnay/rust-toolchain@stable
      - uses: Swatinem/rust-cache@v2

      - name: Install sphinx-rustdocgen
        run: cargo install sphinx-rustdocgen --locked || cargo install sphinx-rustdocgen

      - name: Docs venv with sphinxcontrib-rust
        run: |
          set -euo pipefail
          # Keep the native Sphinx extension on the runner's Rust/C linker.
          python3 -m venv .venv-docs
          .venv-docs/bin/pip install -U pip
          .venv-docs/bin/pip install \
            'sphinx>=9,<10' \
            'shibuya>=2025.12.13,<2026' \
            'sphinx-sitemap>=2.9,<3' \
            'sphinx-copybutton>=0.5.2,<1' \
            'sphinx-design>=0.6,<1' \
            'sphinxcontrib-rust>=1,<2' \
            'sphinx-rustdoc-postprocess>=0.1,<0.2'
          .venv-docs/bin/python -c 'import sphinxcontrib_rust; print("ok")'

      - name: llms.txt matches the Org manual
        run: python3 scripts/gen-llms-txt.py --check

      - name: Build documentation
        run: pixi run -e docs docbld
        env:
          EB_STACK_DOCS_PYTHON: ${{ github.workspace }}/.venv-docs/bin/python

      - name: Install ripgrep
        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends ripgrep

      - name: Assert version-one CLI and Rust API docs
        run: |
          set -euo pipefail
          # Org export must have written the master document.  The Sphinx
          # script refuses to run without it; keep the check here so a
          # workflow change cannot skip it.
          test -s docs/source/index.rst
          # Sphinx splits code literals into per-word <span class="pre"> elements,
          # so multi-word phrases only exist in the tag-stripped text.
          cli_text=$(sed -e 's/&#160;/ /g' -e 's/<[^>]*>//g' docs/build/reference/cli.html)
          grep -q 'package plan' <<<"$cli_text"
          grep -q 'campaign run' <<<"$cli_text"
          grep -q 'eb_package_plan' <<<"$cli_text"
          grep -q 'eb-stack mcp' <<<"$cli_text"
          # In-site Rust API
          test -f docs/build/reference/rust-api.html
          test -f docs/build/crates/eb_stack/lib.html
          grep -q 'plan_new_package' docs/build/crates/eb_stack/lib.html
          test -f docs/build/reference/package-bundles.html
          test -f docs/build/reference/targets.html
          test -f docs/build/reference/campaigns.html
          scripts/check-doc-links.sh docs/build
          # light/dark logos present
          test -f docs/build/_static/logo-light.svg
          test -f docs/build/_static/logo-dark.svg
          grep -q logo-light docs/build/index.html || grep -q logo-dark docs/build/index.html || true
          test -f docs/build/sitemap.xml
          grep -q 'tutorial' docs/build/sitemap.xml
          test -f docs/build/robots.txt
          grep -q 'Sitemap: https://eb-stack.rgoswami.me/sitemap.xml' docs/build/robots.txt
          grep -q 'name="description"' docs/build/index.html
          grep -q 'rel="describedby"' docs/build/index.html
          grep -q 'rel="alternate" type="text/markdown"' docs/build/tutorial.html
          test -f docs/build/llms.txt
          test -f docs/build/llms-full.txt
          test -f docs/build/tutorial.html.md
          test -f docs/build/reference/mcp.html.md

      - name: Install lychee
        uses: taiki-e/install-action@v2
        with:
          tool: lychee@0.24.2

      - name: Link check (lychee)
        run: lychee --config lychee.toml --no-progress 'docs/build/**/*.html' README.md
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Upload docs artifact
        uses: actions/upload-artifact@v7
        with:
          name: sphinx-docs
          path: docs/build

  deploy:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push' && github.repository == 'stackhands/eb-stack'
    needs: build
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Download docs artifact
        uses: actions/download-artifact@v8
        with:
          name: sphinx-docs
          path: docs/build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy docs/build --project-name=eb-stack-docs --branch=main