docs.yml

name: docs

on:
  push:
    branches:
      - master
      - b4b-dev
    paths:
      - 'doc/**'

  pull_request:
    branches:
      - master
      - b4b-dev
    paths:
      - 'doc/**'

  workflow_dispatch:

permissions:
  contents: read
jobs:

  test-build-makefile:
    if: ${{ always() }}
    name: Test building documentation with makefile
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout
        with:
          fetch-depth: 0
          lfs: true
      - name: Install python 3.x
        uses: actions/setup-python
        with:
          python-version: '3.x'
      # https://github.com/actions/cache/blob/main/examples.md#python---pip
      - name: Cache pip
        uses: actions/cache
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-
      - name: Install dependencies
        run: |
          pip install -r doc/requirements.txt
      # Build documentation under ${PWD}/_build
      - name: Build Sphinx docs with makefile
        run: |
          make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build -C doc/ html

  test-doc-builder:
    if: ${{ always() }}
    name: Test building documentation with doc-builder
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout
        with:
          fetch-depth: 0
          lfs: true
      - name: Install python 3.x
        uses: actions/setup-python
        with:
          python-version: '3.x'
      # https://github.com/actions/cache/blob/main/examples.md#python---pip
      - name: Cache pip
        uses: actions/cache
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-
      - name: Install dependencies
        run: |
          pip install -r doc/requirements.txt
      # Build documentation under ${PWD}/_build
      - name: Build Sphinx docs with doc-builder
        run: |
          cd doc && ./build_docs -b ${PWD}/_build -c