eb-stack/.github/workflows/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
# Build the Sphinx site. This workflow does not deploy, does not publish
# GitHub Pages, and does not read secrets.
name: Docs

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

permissions:
  contents: read

concurrency:
  group: docs-build-${{ 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
          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
          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: Assert the site built
        run: |
          set -euo pipefail
          test -s docs/source/index.rst
          test -f docs/build/index.html
          test -f docs/build/get-started.html
          test -f docs/build/install.html
          test -f docs/build/explanation/sharding-admission.html
          test -f docs/build/search.html
          test -f docs/build/changelog.html
          test -f docs/build/contributing.html
          test -f docs/build/reference/cli.html
          test -f docs/build/reference/rust-api.html
          test -f docs/build/crates/eb_stack/lib.html
          # Sphinx splits code literals into per-word <span class="pre"> elements,
          # so multi-word phrases only exist in the tag-stripped text.
          shard_text=$(sed -e 's/&#160;/ /g' -e 's/<[^>]*>//g' docs/build/explanation/sharding-admission.html)
          grep -q 'Copyright (c) eb-stack developers' docs/build/index.html
          grep -q 'stack admit' <<<"$shard_text"
          grep -q 'search' docs/build/index.html