spark-connect-rust/.github/workflows/docs.yml at master · apache/spark-connect-rust · 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
#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
#

name: Docs

on:
  push:
    branches: [master, "branch-*"]
    paths:
      - "docs/**"
      - "mkdocs.yml"
      - ".github/workflows/docs.yml"
  pull_request:
    paths:
      - "docs/**"
      - "mkdocs.yml"
      - ".github/workflows/docs.yml"
      - "crates/**"
  workflow_dispatch:

# `mkdocs gh-deploy` builds the site and pushes it to the `gh-pages` branch,
# which ASF INFRA serves as GitHub Pages (see `.asf.yaml`: `ghp_branch:
# gh-pages`). Only first-party `actions/*` are used, per the ASF Actions policy.
permissions:
  contents: write

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

jobs:
  # PR-time validation (no deploy): catch nav/link/config regressions with
  # `mkdocs build --strict`, and compile the self-contained Rust snippets in the
  # guides against the crate so a doc example can't drift out of sync with the API
  # (the class of bug that shipped `lit`/`SparkSessionBuilder` examples that did not
  # compile). Runs on forks and non-master refs, where the deploy job never runs.
  validate:
    name: Validate docs (strict build + snippet compile)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install MkDocs Material
        run: pip install "mkdocs-material==9.*"
      - name: mkdocs build --strict
        run: mkdocs build --strict
      - name: Install Rust toolchain
        run: |
          rustup toolchain install stable --profile minimal
          rustup default stable
      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y protobuf-compiler
      - name: Build the crate (snippet check compiles against its rlib)
        run: cargo build -p apache-spark-connect
      - name: Compile the guides' Rust snippets
        run: python scripts/check_doc_snippets.py

  build-and-deploy:
    name: Build and deploy the docs site
    runs-on: ubuntu-latest
    # Only ever publish from the canonical repository's master branch (covers
    # both push and workflow_dispatch); forks and non-master refs never deploy.
    if: github.repository == 'apache/spark-connect-rust' && github.ref == 'refs/heads/master'
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install MkDocs Material
        run: pip install "mkdocs-material==9.*"

      - name: Build and deploy to the gh-pages branch
        run: mkdocs gh-deploy --force --no-history