generate-docs.yml

#----------------------------------------------
# Generate and upload documentation (only on push to master)
#----------------------------------------------

name: Generate documentation
on:
  pull_request:
    # on pull request we just want to build to see nothing is broken
    paths:
    - "README.md"
    - "doc/**"
    - ".github/workflows/generate-docs.yml"
    - "mkdocs.yml"
  push:
    branches:
      - master

jobs:
  publish-docs:
    runs-on: ubuntu-20.04
    strategy:
      matrix:
        python-version: [3.9]
    steps:
      - name: Check out the repo
        uses: actions/checkout@v3

      - name: Setup Python version
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install Poetry
        uses: snok/install-poetry@v1.3
        with:
          virtualenvs-create: true
          virtualenvs-in-project: true

      - name: Load cached venv
        id: cached-poetry-dependencies
        uses: actions/cache@v3
        with:
          path: .venv
          key: venv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}

      - name: Install dependencies
        run: poetry install
        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'

      - name: Generate documentation
        run: bash ./build_mkdocs.sh

      # generating openapi documentation
      # we do this after mkdocs to overwrite api.html file
      - name: Generate openapi html with ghcr.io/redocly/redoc/cli:latest
        run : |
          docker run --rm \
            -v $(pwd)/doc/references:/data -v $(pwd)/gh_pages/:/output \
            ghcr.io/redocly/redoc/cli:latest \
            build -o /output/references/api/index.html api.yml && \
          sudo chown $UID -R gh_pages

      # Deploy docs to gh_pages if we are pushing to master
      # Example from https://github.com/marketplace/actions/deploy-to-github-pages
      - name: Deploy 🚀
        # we only deploy on push to master
        if: |
          github.event_name == 'push' && github.event.ref == 'refs/heads/master'
        uses: JamesIves/github-pages-deploy-action@v4.4.1
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages # The branch the action should deploy to.
          FOLDER: gh_pages # The folder the action should deploy.
          CLEAN: true # Automatically remove deleted files from the deploy branch