main.yml

name: Build docs and check links
on: [push, pull_request]
env:
  PYTHONWARNINGS: error
  PIP: python -m pip
  SPHINX: python -m sphinx -W --keep-going --color
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - name: Clone repo
      uses: actions/checkout@v3
      with:
        fetch-depth: 0
        submodules: true
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: "3"
    - name: Double-check Python version
      run: |
        python --version
    - name: Install Python package
      env:
        PYTHONWARNINGS: error,default::DeprecationWarning
      run: |
        $PIP install .
    - name: Install docs dependencies
      env:
        PYTHONWARNINGS: error,default::DeprecationWarning
      run: |
        $PIP install -r doc/requirements.txt
    - name: Build HTML
      run: |
        $SPHINX -d _build/doctrees/ doc/ _build/html/ -b html
    - name: Upload error log
      uses: actions/upload-artifact@v3
      if: failure()
      with:
        name: build-log
        path: /tmp/sphinx-err-*.log
    - name: Check links
      run: |
        $SPHINX -d _build/doctrees/ doc/ _build/linkcheck/ -b linkcheck
    - name: Upload linkcheck results
      uses: actions/upload-artifact@v3
      if: ${{ success() || failure() }}
      with:
        name: linkcheck
        path: _build/linkcheck/output.*