sphinx-docs.yml

# This workflow will install Python dependencies and run builddocs.py to build HTML docs using Sphinx.

name: Build HTML Docs

on:
  push:
    paths:
      # Trigger only when docs/ folder is updated
      - 'docs/**'
    tags:
      - v[0-9]+.[0-9]+.[0-9]+**
    branches: [ master ]
  workflow_dispatch:
    # Workflow can also be triggered manually
    inputs:
      version:
        description: 'Doc version(s) to build (latest, all, stable, <tag>)'
        required: true
        default: 'latest'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python 3.8
        uses: actions/setup-python@v2
        with:
          python-version: 3.8
      - name: Install pip and dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -U sphinx
          pip install -U sphinx-rtd-theme
          pip install -U Mako
          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
      - name: Make sure that the themes folder is empty so we get fresh stuff
        run: rm -rf docs/themes/*
      - name: Run builddocs script
        run: |
          if [[ ! -z "${{github.event.inputs.version}}" ]]; then
            python docs/builddocs.py --version ${{github.event.inputs.version}} --theme sphinx_rtd_theme
          else
            python docs/builddocs.py --theme sphinx_rtd_theme
          fi
          # Always apply the theme override (in case of older builds with a different theme in conf.py)
      - name: Clone gh-pages branch folder and copy HTML docs into it
        run: |
          git clone ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git --branch gh-pages --single-branch gh-pages
          cp -r build/docs/* gh-pages/
      - name: Update index.html for GitHub Pages
        run: python .github/workflows/docs_index.py ./gh-pages
      - name: Stage and commit gh-pages changes
        run: |
          cd gh-pages
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add .
          git commit -m "Update documentation" -a || true
          # Above command will fail if there are no changes: ignore return code
      - name: Push changes
        uses: ad-m/github-push-action@master
        with:
          branch: gh-pages
          directory: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}