docs.yaml

name: Build and Deploy Documentation
on:
  push:
    branches:
      - develop
      - 'feature/*'
      - 'main/*'
      - 'bugfix/*'
      - 'release/*'
    paths:
      - 'docs/**'
  pull_request_target:
    types: [issues, opened, reopened, synchronize]
    paths:
      - 'docs/**'

jobs:

  documentation:
    
    permissions:
      pull-requests: 'write'

    runs-on: ubuntu-latest
    name: Build and deploy documentation

    steps:
    - name: Setup Python
      uses: actions/setup-python@v4
      with:
        python-version: "3.9"

    - name: Install (upgrade) python dependencies
      run: |
        pip install --upgrade pip sphinx sphinx-gallery sphinx_rtd_theme sphinxcontrib-bibtex

    - name: Checkout
      uses: actions/checkout@v3

    - name: Build documentation
      run: |
        ./.github/scripts/build_docs.sh

    - name: Upload documentation (on success)
      uses: actions/upload-artifact@v3
      if: always()
      with:
        name: documentation
        path: artifact/documentation

    - name: Upload warnings (on failure)
      uses: actions/upload-artifact@v3
      if: failure()
      with:
        name: documentation_warnings.log
        path: artifact/doc_warnings.log
        if-no-files-found: ignore

    - name: Comment ReadDocs
      uses: actions/github-script@v6
      with:
        script: |
          const message = `
          Link to ReadTheDocs sample build for this PR can be found at:
          https://global-workflow--${{ github.event.pull_request.number }}.org.readthedocs.build/en/${{ github.event.pull_request.number }}
          `
          github.rest.issues.createComment({
           issue_number: context.issue.number,
           owner: context.repo.owner,
           repo: context.repo.repo,
           body: message 
          })