mlflow--mlflow/.github/workflows/docs.yml

name: docs

on:
  push:
    paths:
      - pyproject.toml
      - uv.lock
      - mlflow/**
      - docs/**
      - .github/workflows/docs.yml
      - .github/actions/setup-node/**
    branches:
      - master
  pull_request:
    types:
      - opened
      - synchronize
      - reopened
    paths:
      - pyproject.toml
      - uv.lock
      - mlflow/**
      - docs/**
      - .github/workflows/docs.yml
      - .github/actions/setup-node/**

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

defaults:
  run:
    shell: bash
    working-directory: docs

permissions: {}

jobs:
  check:
    if: github.event_name != 'pull_request' || (github.event.pull_request.draft == false || github.event.pull_request.user.login == 'Copilot' && github.event.pull_request.user.type == 'Bot')
    permissions:
      contents: read
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup-node
      - name: Install dependencies
        run: |
          npm ci
      - name: Check package-lock.json is up-to-date
        run: |
          npm install --package-lock-only --no-audit --no-fund
          git diff --exit-code package-lock.json || {
            echo "package-lock.json is out of date. Run 'npm install --package-lock-only' locally and commit the result."
            exit 1
          }
      - name: Run lint
        run: |
          npm run eslint
      - name: Run prettier
        run: |
          npm run prettier:check

  build:
    if: github.event_name != 'pull_request' || (github.event.pull_request.draft == false || github.event.pull_request.user.login == 'Copilot' && github.event.pull_request.user.type == 'Bot')
    permissions:
      contents: read
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup-java
      - uses: ./.github/actions/setup-node
      - uses: ./.github/actions/setup-python
      - name: Install dependencies
        working-directory: .
        run: |
          uv sync --group docs --extra gateway
          uv pip install -r requirements/torch.txt
      - run: |
          npm ci
      - uses: ./.github/actions/show-versions
      - run: |
          npm run convert-notebooks
      - name: Set alias
        id: alias
        env:
          EVENT_NAME: ${{ github.event_name }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          if [ "$EVENT_NAME" = "push" ]; then
            ALIAS="dev"
          else
            ALIAS="pr-$PR_NUMBER"
          fi
          echo "value=$ALIAS" >> $GITHUB_OUTPUT
      - name: Build docs
        env:
          GTM_ID: "GTM-TEST"
          API_REFERENCE_PREFIX: https://${{ steps.alias.outputs.value }}--mlflow-docs-preview.netlify.app/docs/
        run: |
          npm run build-all -- --no-r --use-npm
      - name: Check API inventory
        run: |
          if [ -n "$(git status --porcelain api_reference/api_inventory.txt)" ]; then
            echo "The API inventory file 'docs/api_reference/api_inventory.txt' is outdated (see the diff below)."
            echo "Please update it by running 'make rsthtml' in the 'docs/api_reference' directory, or post a comment '/autoformat' on this PR if you're a maintainer/collaborator."
            echo "If the new APIs should be marked as experimental, please decorate them with '@experimental'."
            echo "Diff:"
            git diff api_reference/api_inventory.txt
            exit 1
          fi
      - name: Check sitemap
        run: |
          npm run sitemap -- https://mlflow.org/docs/latest/sitemap.xml ./build/latest/sitemap.xml
      - name: Move build artifacts
        run: |
          mkdir -p /tmp/docs-build/docs
          mv build/latest /tmp/docs-build/docs/latest

          # Create `docs/versions.json` for the version selector in the API reference
          VERSION="$(uv version | cut -d' ' -f2)"
          echo "{\"versions\": [\"$VERSION\"]}" > /tmp/docs-build/docs/versions.json
      - name: Upload build artifacts
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: docs-build-${{ github.run_id }}
          path: /tmp/docs-build
          retention-days: 1
          if-no-files-found: error

  test-examples:
    if: github.event_name != 'pull_request' || (github.event.pull_request.draft == false || github.event.pull_request.user.login == 'Copilot' && github.event.pull_request.user.type == 'Bot')
    permissions:
      contents: read
    timeout-minutes: 30
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: docs/api_reference
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup-python
      - name: Install dependencies
        working-directory: .
        run: |
          uv sync --group docs --extra gateway
          uv pip install -r requirements/torch.txt
      - name: Extract examples
        run: |
          uv run source/testcode_block.py
      - name: Run tests
        run: |
          uv run pytest .examples

  r:
    if: (github.event_name != 'pull_request' || (github.event.pull_request.draft == false || github.event.pull_request.user.login == 'Copilot' && github.event.pull_request.user.type == 'Bot'))
    permissions:
      contents: read
    timeout-minutes: 15
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          persist-credentials: false
      - name: Build docs
        working-directory: docs/api_reference
        run: |
          ./build-rdoc.sh
          if [ -n "$(git status --porcelain)" ]; then
            echo "The following files have changed:"
            git status --porcelain
            exit 1
          fi