docs.yml

# Workflow for deploying static content to GitHub Pages
name: '📚 Publish docs via GitHub Pages'

# build the documentation whenever there are new commits on main
on:
  workflow_dispatch:
    inputs:
      dry-run:
        required: false
        default: true
        type: boolean

  workflow_call:
    inputs:
      dry-run:
        required: false
        default: true
        type: boolean

    outputs:
      page-url:
        description: 'URL to the docs published on GitHub Pages'
        value: ${{ jobs.deploy.outputs.page-url }}

jobs:
  config-prep:
    runs-on: ubuntu-latest
    outputs:
      env: ${{ steps.read-file.outputs.content }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Read YAML file
        id: read-file
        uses: ./.github/actions/read-yaml
        with:
          path: .github/settings/config.yml
          filter: '.default.env'

  # Build the documentation and upload the static HTML files as an artifact.
  build:
    needs: config-prep
    env: ${{ fromJson(needs.config-prep.outputs.env) }}

    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Set up Python ${{ env.python-version }}
        id: setup-python
        uses: actions/setup-python@v4
        with:
          python-version: ${{ env.python-version }}

      - name: Set up Poetry ${{ env.poetry-version }}
        id: setup-poetry
        uses: ./.github/actions/setup-poetry
        with:
          cache-path: ${{ env.poetry-cache-paths }}
          cache-key: ${{ format(env.poetry-cache-key-fmt, env.poetry-version, runner.os, steps.setup-python.outputs.python-version) }}
          poetry-version: ${{ env.poetry-version }}
          poetry-home: ${{ env.poetry-home }}
          poetry-path: ${{ env.poetry-path }}

      - name: Install dependencies
        run: poetry install --no-interaction --no-root --with docs

      - name: Build
        run: |
          poetry run python ./docs/make.py

      - uses: actions/upload-pages-artifact@v1
        with:
          path: docs/build/

  # Deploy the artifact to GitHub pages.
  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
  deploy:
    needs: build
    if: ${{ !inputs.dry-run }}
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    outputs:
      page-url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v2