docs.yaml

name: Generate docs

on: 
  push:
  workflow_dispatch:

# 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: ${{ github.workflow }}-${{ github.ref_name }}
  cancel-in-progress: false

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  generate-docs:
    name: docs
    runs-on: ubuntu-latest
    # only on default branch
    if:  ${{ github.ref_name == github.event.repository.default_branch || github.event_name == 'workflow_dispatch' }}

    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 1

      - name: Install bz2
        run: |
          sudo apt-get update && sudo apt-get install libbz2-dev -y

      - name: Install Poetry
        run: |
          PIPX_BIN_DIR=/usr/local/bin pipx install poetry

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.8"
          cache: poetry
          cache-dependency-path: poetry.lock

      - name: Set Poetry environment
        run: |
          poetry env use 3.8

      - name: Install dependencies
        run: |
          poetry install

      # Not elegant, but pdoc can't handle assets paths gracefully
      - name: Generate docs with pdoc
        run: |
          cd docs
          poetry run pdoc --output-dir . \
            --favicon https://raw.githubusercontent.com/ssc-oscar/python-woc/master/docs/favicon.ico \
            --logo https://raw.githubusercontent.com/ssc-oscar/python-woc/master/docs/woc.png ../woc

      - name: Setup Pages
        uses: actions/configure-pages@v5
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'docs'
      
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4