api-docs.yml

---
name: API Docs
on:
  workflow_dispatch:
    inputs:
      deploy-gh-pages:
        description: Deploy GH Pages
        required: true
        type: boolean
        default: false
      image-tag:
        default: latest
        description: Development Docker Image Tag
  pull_request:
    paths:
      - doc/**.rst
      - doc/create-doc
      - doc/clean-doc
      - doc/*.py
      - khiops/**.py
      - .github/workflows/api-docs.yml
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  id-token: write
  packages: read
  pages: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest
# queued. However, do NOT cancel in-progress runs as we want to allow these production deployments
# to complete.
concurrency:
  group: pages
  cancel-in-progress: false
jobs:
  build:
    runs-on: ubuntu-22.04
    container:
      # 'latest' default image tag cannot be set as an environment variable,
      # because the `env` context is only accessible at the step level;
      # hence, it is hard-coded
      image: |-
        ghcr.io/khiopsml/khiops-python/khiopspydev-ubuntu22.04:${{ inputs.image-tag || 'latest' }}
      # Use the 'runner' user (1001) from github so checkout actions work properly
      # https://github.com/actions/runner/issues/2033#issuecomment-1598547465
      options: --user 1001
    steps:
      - name: Checkout khiops-python
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Checkout khiops-python-tutorial
        uses: actions/checkout@v4
        with:
          repository: khiopsml/khiops-python-tutorial
          path: doc/khiops-python-tutorial
      - name: Add pip scripts directory to path
        run: echo PATH="$PATH:/github/home/.local/bin" >> "$GITHUB_ENV"
      - name: Install doc build requirements
        run: |
          # Install package itself to install the samples datasets
          pip3 install .
          kh-download-datasets --force-overwrite
          kh-status

          # Install the doc python requirements
          cd doc
          pip3 install -U -r requirements.txt
      - name: Build Sphinx Documentation
        run: |
          cd doc
          ./create-doc -t
      - name: Upload the docs as an artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: doc/_build/html/
  # Deploy only when the user explicitly (and manually) orders it
  deploy:
    if: github.event_name == 'workflow_dispatch' && inputs.deploy-gh-pages == true
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Deploy API Docs to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4