.github/workflows/python-docs.yml

# 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: "build-python-docs-and-share-as-artifact"

on:
  workflow_dispatch:
  schedule:
    - cron: "0 2 * * 6" # runs every saturday at 00:00:00

jobs:
  python-docs-artifact-building:
    runs-on: ubuntu-latest
    steps:
      - name: clone
        uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - name: create working branch & set GitHub config
        run: |
          git checkout -b build-python-docs-${{ github.run_id }}
          git config user.name 'github-actions[bot]'
          git config user.email 'github-actions[bot]@users.noreply.github.com'

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

      - name: Install and configure Poetry
        uses: snok/install-poetry@v1
        with:
          version: 1.6.1
          virtualenvs-create: true
          virtualenvs-in-project: true

      - name: Cache Python dependencies
        uses: actions/cache@v4
        with:
          path: .venv
          key: ${{ runner.os }}-pip-doc-${{ hashFiles('**/pyproject.toml', '**/poetry.lock') }}
          restore-keys: |
            ${{ runner.os }}-pip-doc-

      - name: Install Python dependencies
        working-directory: ./streampipes-client-python
        run: poetry install --with docs

      - name: Build Python docs
        working-directory: ./streampipes-client-python
        run: |
          poetry run mike deploy dev -u --deploy-prefix ./streampipes-client-python/docs-tmp -b build-python-docs-${{ github.run_id }}
          git reset --hard  # undo local changes that delete generated doc files

      - name: Publish Python docs as artifact
        uses: actions/upload-artifact@v4
        with:
          name: streampipes-python-docs
          path: |
            streampipes-client-python/docs-tmp/dev/
            !streampipes-client-python/docs-tmp/versions.json  # exclude versions file because this would overwrite existing versions and aliases
          retention-days: 5