doc.yml

name: documentation

on:
  # Trigger the workflow on push or pull request,
  # but only for the main branch
  push:
    branches:
      - master
  pull_request:
    branches:
      - master
  # Also trigger on page_build, as well as release created events
  page_build:
  release:
    types: # This configuration does not affect the page_build event above
      - created

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
      with:
        persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal access token.
        fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
    # - name: Setup tmate session   # Debugging
    #   uses: mxschmitt/action-tmate@v3
    - uses: ammaraskar/sphinx-action@master
      with:
        pre-build-command: |
            python -m pip install -r requirements.txt
            python -m pip install -r docs/requirements.txt
            rm -f pystellibs.*rst
            # re-generate API documentation
            make apidoc
        docs-folder: "docs/"
    # Publish built docs to gh-pages branch.
    # ===============================
    - name: Commit documentation changes
      run: |
        git clone https://github.com/ammaraskar/sphinx-action-test.git --branch gh-pages --single-branch gh-pages
        cp -r docs/_build/html/* gh-pages/
        cd gh-pages
        touch .nojekyll
        git config --local user.email "action@github.com"
        git config --local user.name "GitHub Action"
        git add .
        git commit -m "Update documentation" -a || true
        # The above command will fail if no changes were present, so we ignore
        # that.
    - name: Push changes
      uses: ad-m/github-push-action@master
      with:
        branch: gh-pages
        directory: gh-pages
        github_token: ${{ secrets.GITHUB_TOKEN }}
        force: true
    # ===============================