docs_check_test_build.yml

name: "Build Docs"

# see: https://help.github.com/en/actions/reference/events-that-trigger-workflows
on:
  # Trigger the workflow on push or pull request,
  # but only for the main branch
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  sphinx-check:
    if: false # always skip job
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v2

    - uses: ammaraskar/sphinx-action@master
      with:
        # git is required to clone the docs theme
        # before custom requirement are resolved https://github.com/ammaraskar/sphinx-action/issues/16
        pre-build-command: "apt-get update -y && apt-get install -y git && pip install -r requirements/docs.txt"
        docs-folder: "docs/"
        repo-token: "${{ secrets.GITHUB_TOKEN }}"

  test-docs:
    if: false # always skip job
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Set up Python 3.9
        uses: actions/setup-python@v2
        with:
          python-version: 3.9

      # Note: This uses an internal pip API and may not always work
      # https://github.com/actions/cache/blob/master/examples.md#multiple-oss-in-a-workflow
      - name: Cache pip
        uses: actions/cache@v2
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('requirements/install.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      - name: Install dependencies
        run: |
          # python -m pip install --upgrade --user pip
          pip install --requirement requirements/install.txt --upgrade-strategy only-if-needed
          pip install --requirement requirements/extra.txt
          pip install --requirement requirements/docs.txt
          python --version ; pip --version ; pip list
        shell: bash

      - name: Test Documentation
        env:
          SPHINX_MOCK_REQUIREMENTS: 0
        run: |
          # First run the same pipeline as Read-The-Docs
          apt-get update && sudo apt-get install -y cmake
          cd docs
          make doctest
          make coverage

  build-docs:
    if: false
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v2

    - name: Set up Python 3.9
      uses: actions/setup-python@v2
      with:
        python-version: 3.9

    # Note: This uses an internal pip API and may not always work
    # https://github.com/actions/cache/blob/master/examples.md#multiple-oss-in-a-workflow
    - name: Cache pip
      uses: actions/cache@v2
      with:
        path: ~/.cache/pip
        key: ${{ runner.os }}-pip-${{ hashFiles('requirements/install.txt') }}
        restore-keys: |
          ${{ runner.os }}-pip-

    - name: Install dependencies
      run: |
        sudo apt-get update && sudo apt-get install pandoc
        sudo apt-get install -y cmake
        python -m pip install --upgrade pip
        pip install -U pip wheel
        pip install -r requirements/docs.txt
      shell: bash

    - name: Build Docs
      run: |
        cd docs
        bash build_docs.sh

    - name: Upload built docs
      uses: actions/upload-artifact@v2
      with:
        name: docs-results-${{ runner.os }}-${{ matrix.python-version }}-${{ matrix.requires }}
        path: docs/build/html/
      # Use always() to always run this step to publish test results when there are test failures
      if: success()