docs.yml

name: build docs

# TODO: If we have `docs` directories within each package, we should then
# add them here under `paths` to listen for changes
on:
  push:
    branches:
      - master
      - develop
      - release-*
    paths:
      - 'docs/**'
      - '**.rst'
  pull_request:
    branches:
      - master
      - develop
      - release-*
    paths:
      - 'docs/**'
      - '**.rst'

defaults:
  run:
    working-directory: docs

jobs:
  tests:
    name: "build & check docs"
    runs-on: "ubuntu-latest"
    steps:
      - uses: "actions/checkout@v2"
      - uses: "actions/setup-python@v1"
        with:
          python-version: "3.8"
      - name: "Install dependencies"
        run: |
          set -xe
          python -VV
          python -m site
          python -m pip install --upgrade pip setuptools
          python -m pip install --upgrade -r requirements.txt
          python -m pip install -e ../core/
          python -m pip install -e ../cli/
          python -m pip install -e ../devtools/
          python -m pip install -e ../lib/
          python -m pip install -e ../exec/
          python -m pip install -e ../audio/
      - name: "Build docs"
        run: "sphinx-build -n -T -W -b html -d build/doctrees src src/html"
      # Temporary workaround for https://gitlab.com/documatt/sphinx-reredirects/-/merge_requests/1
      - name: "Check broken links [temporary workaround]"
        run: "make linkcheck"
      # Uncomment two lines below if/when the above linked PR gets addressed
      # - name: "Check broken links"
      #   run: "sphinx-build -n -T -W -b linkcheck -d build/docstrees src src/linkcheck"

      # Un-comment if we want to add this to our build process; commenting it out
      # for now because it might be too obtrusive
      # - name: "Spell check docs"
      #   run: |
      #     sudo apt-get install -y libenchant
      #     sphinx-build -n -T -W -b spelling -d build/docstrees src src/spellcheck
      - name: "Assert Apache License Headers & Copyright in docs/"
        run: |
          pip install apache-license-check
          apache-license-check --include-empty --copyright "Spotify AB"
      - name: "Assert Apache License Headers & Copyright in examples/"
        working-directory: examples
        run: |
          pip install apache-license-check
          apache-license-check --include-empty --copyright "Spotify AB"