docs.yml

# Github action to build docs and, if on main, deploy to the gh-pages branch
name: docs
on: [push, pull_request]
jobs:
  sphinx:
    runs-on: ubuntu-latest
    # The permissions are required to deploy to the gh-pages branch by the 
    # gh-actions official action, might not be necssary for our use-case
    permissions:
      contents: write
    steps:
      # Checkout and build the docs with sphinx
      - name: Checkout
        uses: actions/checkout@v4
      - name: Build HTML
        uses: ammaraskar/sphinx-action@7.4.7
        with: 
          docs-folder: "docs/"
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
            name: html-docs
            path: docs/build/html/
        # Deploys to the gh-pages branch if the commit was made to main, the 
        # gh-pages then takes over serving the html
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        if: github.ref == 'refs/heads/main'
        with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: docs/build/html