build-docs.yaml

name: build the docs

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["**"]

jobs:
  build-docs:
    timeout-minutes: 5
    runs-on: ubuntu-latest

    steps:
      #------------------------------------
      #  check-out repo and set-up python
      #------------------------------------
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up python
        id: setup-python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      #------------------------------
      #  install & configure poetry
      #------------------------------
      - name: Install Poetry
        uses: snok/install-poetry@v1
        with:
          virtualenvs-create: true
          virtualenvs-in-project: true
          installer-parallel: true

      #----------------------------------
      #  install dynamic version plugin
      #----------------------------------
      - name: Install poetry-dynamic-versioning
        run: poetry self add "poetry-dynamic-versioning[plugin]"

      #------------------------------------
      #  load cached venv if cache exists
      #------------------------------------
      - name: Load cached venv
        id: cached-poetry-dependencies
        uses: actions/cache@v4
        with:
          path: .venv
          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}

      #------------------------
      #  install root project
      #------------------------
      - name: Install library
        run: poetry install --no-interaction --with docs,dev,server

      #------------------
      #  build the docs
      #------------------
      - name: Build the docs
        run: poetry run make --directory=doc html