slint/.github/workflows/build_docs.yaml

# Copyright © SixtyFPS GmbH <info@slint.dev>
# SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-Royalty-free-2.0 OR LicenseRef-Slint-Software-3.0

# Build various demo binaries, c++ packages and documentation and publish them on the website
# Job 1 (rust-cpp-docs): Build Rust and C++ documentation
# Job 2 (astro-docs-tests): Generate screenshots, build Astro docs and run tests
# Job 3 (node-python-docs): Build Node and Python documentation
# Job 4 (check-warnings): Validate docs for warnings

name: Build docs

on:
    workflow_call:
      secrets:
        READ_WRITE_PRIVATE_KEY:
          required: true
      inputs:
        release:
          type: string
          default: "false"
          required: false
          description: "Release? Enable options for building binaries for a release (i.e. apply a nightly tag, nightly version)"
        app-id:
          type: string
          required: true

jobs:
    # Job 1: Build Rust and C++ documentation
    rust-cpp-docs:
        runs-on: ubuntu-24.04
        env:
            # Allow deprecated warning because we are using nightly and some things might be deprecated in nightly
            # for which the stable alternative is not yet available.
            RUSTFLAGS: -D warnings -W deprecated
            RUSTDOCFLAGS: --html-in-header=/home/runner/work/slint/slint/docs/astro/src/utils/slint-docs-highlight.html -D warnings -W deprecated --cfg docsrs -Zunstable-options --generate-link-to-definition
            SLINT_NO_QT: 1
            CARGO_INCREMENTAL: false
            RELEASE_INPUT: ${{ inputs.release }}
        steps:
            - uses: actions/checkout@v5
            - name: Set up crate rustdoc link
              run: |
                  rgb_version=`grep 'rgb = '  internal/core/Cargo.toml | sed 's/^.*"\(.*\)"/\1/'`
                  echo "RUSTDOCFLAGS=$RUSTDOCFLAGS --extern-html-root-url rgb=https://docs.rs/rgb/$rgb_version/ --extern-html-root-url android_activity=https://docs.rs/android-activity/0.5/ --extern-html-root-url raw_window_handle=https://docs.rs/raw_window_handle/0.6 --extern-html-root-url winit=https://docs.rs/winit/0.30 --extern-html-root-url wgpu=https://docs.rs/wgpu/26 --extern-html-root-url input=https://docs.rs/input/0.9" >> $GITHUB_ENV
            - uses: ./.github/actions/install-linux-dependencies
            - uses: ./.github/actions/setup-rust
              with:
                  toolchain: nightly
                  target: aarch64-linux-android
            - name: Install apt dependencies
              run: sudo apt-get install doxygen
            - uses: baptiste0928/cargo-install@v3
              with:
                  crate: cargo-about
                  version: "=0.6.6"
            - name: Install uv
              uses: astral-sh/setup-uv@v7
            - name: Build Cpp docs
              run: |
                CPPDOCS_EXTRA_FLAGS=""
                if [ "$RELEASE_INPUT" != "true" ]; then
                    CPPDOCS_EXTRA_FLAGS="--experimental"
                fi
                cargo xtask cppdocs --show-warnings $CPPDOCS_EXTRA_FLAGS
            - name: "Rust docs"
              run: cargo doc -p slint -p slint-build -p slint-interpreter --no-deps --all-features
            - name: "Rust android-activity and i-slint-backend-winit"
              run: |
                  cargo doc -p i-slint-backend-android-activity -p i-slint-backend-winit -p i-slint-backend-testing --no-deps --target aarch64-linux-android --features=i-slint-backend-android-activity/native-activity,i-slint-backend-android-activity/aa-06,i-slint-backend-winit/raw-window-handle-06,i-slint-backend-winit/renderer-femtovg
                  cp -r target/aarch64-linux-android/doc/i_slint_backend_android_activity/ target/doc/
                  cp -r target/aarch64-linux-android/doc/i_slint_backend_winit/ target/doc/
                  cp -r target/aarch64-linux-android/doc/i_slint_backend_testing/ target/doc/
            - name: "Prepare Rust and C++ docs for website directory structure"
              run: |
                  mkdir -p artifact/docs
                  mv target/doc artifact/docs/rust
                  mv target/cppdocs/html artifact/docs/cpp
            - name: "Upload Rust/C++ Docs Artifacts"
              uses: actions/upload-artifact@v5
              with:
                  name: docs-rust-cpp
                  path: artifact
            - name: "Check for docs warnings in internal crates"
              run: cargo doc --workspace --no-deps --all-features --exclude slint-node --exclude pyslint --exclude mcu-board-support --exclude mcu-embassy --exclude printerdemo_mcu --exclude carousel --exclude test-* --exclude plotter --exclude uefi-demo --exclude ffmpeg --exclude gstreamer-player --exclude slint-cpp --exclude slint-python

    # Job 2: Build Astro docs and run tests
    astro-docs-tests:
        runs-on: ubuntu-24.04
        env:
            RUSTFLAGS: -D warnings -W deprecated
            RUSTDOCFLAGS: --html-in-header=/home/runner/work/slint/slint/docs/astro/src/utils/slint-docs-highlight.html -D warnings -W deprecated --cfg docsrs -Zunstable-options --generate-link-to-definition
            SLINT_NO_QT: 1
            CARGO_INCREMENTAL: false
            RELEASE_INPUT: ${{ inputs.release }}
        steps:
            - uses: actions/checkout@v5
            - uses: pnpm/action-setup@v4.2.0
              with:
                version: 10.18.2
            - uses: actions/setup-node@v6
              with:
                node-version: 22
                package-manager-cache: false
            - uses: ./.github/actions/install-linux-dependencies
            - name: Install MS fonts for comic sans needed by one of the screenshots in the docs
              run: |
                  echo ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true | sudo debconf-set-selections
                  sudo apt-get install ttf-mscorefonts-installer -y
            - uses: ./.github/actions/setup-rust
              with:
                  toolchain: stable
                  target: aarch64-linux-android
                  cache: false
            - name: "Generate Screenshots for Example Snippets"
              run: cargo run --release -p slint-docsnapper -- docs/astro/src/content --overwrite
            - name: "Install Node dependencies"
              run: pnpm i --frozen-lockfile
            - name: Extract Version from Cargo.toml
              id: version
              run: |
                version=$(awk '/^\[workspace.package\]/ {found=1} found && /^version = / {gsub(/version = |"/, "", $0); print $0; exit}' Cargo.toml)
                if [[ -z "$version" ]]; then
                  echo "Version not found"
                  exit 1
                fi
                  echo "VERSION=$version" >> $GITHUB_OUTPUT
            - name: Update URL for sitemap in site-config.ts
              run: |
                version="${{ steps.version.outputs.VERSION }}"
                if [ "$RELEASE_INPUT" != "true" ]; then
                    base_url="https://snapshots.slint.dev"
                    base_path="/master/docs/slint/"
                    slint_download_version=nightly
                else
                    base_url="https://releases.slint.dev"
                    base_path="/$version/docs/slint/"
                    slint_download_version=v$version
                fi
                sed -i "s|BASE_URL = \".*\"|BASE_URL = \"$base_url\"|" docs/common/src/utils/site-config.ts
                sed -i "s|BASE_PATH = \".*\"|BASE_PATH = \"$base_path\"|" docs/common/src/utils/site-config.ts
                sed -i "s|SLINT_DOWNLOAD_VERSION = \".*\"| SLINT_DOWNLOAD_VERSION = \"$slint_download_version\"|" docs/common/src/utils/site-config.ts
            - name: "Slint Language Documentation"
              run: cargo xtask slintdocs
            - name: Spellcheck
              working-directory: docs/astro
              run: pnpm spellcheck
            - name: Install Playwright
              working-directory: docs/astro
              run: pnpm exec playwright install --with-deps
            - name: Run Playwright tests
              working-directory: docs/astro
              run: pnpm exec playwright test
            - name: Publish Test Summary Results
              working-directory: docs/astro
              run: npx github-actions-ctrf playwright-report/ctrf-report.json
            - name: Upload test results
              if: always()
              uses: actions/upload-artifact@v5
              with:
                name: playwright-test-report
                path: docs/astro/playwright-report/
                retention-days: 30
            - name: Debug - Verify dist exists before upload
              run: |
                echo "=== Checking docs/astro/dist ==="
                ls -la docs/astro/ || echo "docs/astro/ does not exist"
                ls -la docs/astro/dist/ || echo "docs/astro/dist/ does not exist"
                echo "File count in dist: $(find docs/astro/dist -type f 2>/dev/null | wc -l)"
                echo "First 10 files:"
                find docs/astro/dist -type f 2>/dev/null | head -10
            - name: "Prepare docs for website structure"
              run: |
                mkdir -p artifact/docs
                mv docs/astro/dist artifact/docs/slint
            - name: "Upload Astro Docs Artifacts"
              uses: actions/upload-artifact@v5
              with:
                  name: docs-astro
                  path: artifact

    # Job 3: Build Node and Python documentation
    node-python-docs:
        runs-on: ubuntu-24.04
        env:
            RELEASE_INPUT: ${{ inputs.release }}
        steps:
            - uses: actions/checkout@v5
            - uses: pnpm/action-setup@v4.2.0
              with:
                version: 10.18.2
            - uses: actions/setup-node@v6
              with:
                node-version: 22
                package-manager-cache: false
            - uses: ./.github/actions/install-linux-dependencies
            - uses: ./.github/actions/setup-rust
              with:
                  toolchain: stable
                  target: aarch64-linux-android
                  cache: false
            - uses: baptiste0928/cargo-install@v3
              with:
                  crate: cargo-about
                  version: "=0.6.6"
            - name: Install uv
              uses: astral-sh/setup-uv@v7
            - name: "Install Node dependencies"
              run: pnpm i --frozen-lockfile
            - name: "Node docs"
              run: pnpm run docs
              working-directory: api/node
            - name: Setup headless display
              uses: pyvista/setup-headless-display-action@v4
            - name: "Python docs"
              run: uv run build_docs.py
              working-directory: api/python/slint
            - name: "Prepare docs for website structure"
              run: |
                  mkdir -p artifact/docs
                  mv api/node/docs artifact/docs/node
                  mv api/python/slint/docs artifact/docs/python
            - name: "Upload Python/Node Docs Artifacts"
              uses: actions/upload-artifact@v5
              with:
                  name: docs-node-python
                  path: artifact