docs.yml

name: Build and publish docs

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:
      - main
    # Sequence of patterns matched against refs/tags
    tags:
      - v*

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout source
      uses: actions/checkout@v3
      with:
        # require all of history to see all tagged versions' docs
        fetch-depth: 0
    - name: Set up Python 3.10
      uses: actions/setup-python@v4
      with:
        python-version: '3.10'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip setuptools wheel
        python -m pip install -e .[docs,viz]
        python -m pip install git+https://github.com/dls-controls/sphinx-multiversion@only-arg
    - name: Checkout gh-pages
      # As we already did a deploy of gh-pages above, it is guaranteed to be there
      # so check it out so we can selectively build docs below
      uses: actions/checkout@v3
      with:
          ref: gh-pages
          path: docs/_build
    - name: Build docs
      # Use the args we normally pass to sphinx-build, but run sphinx-multiversion
      run: |
        make -C docs/ html
        touch docs/_build/.nojekyll
        cp docs/redirect.html docs/_build/index.html
    - name: Publish docs to gh-pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/_build
        keep_files: true