python_sphinx_docs.yml

name: Build Python Sphinx Docs and push to gh-pages

on:
    push:
        branches: master
        paths:
          - 'python/**'
          - '.github/workflows/python_sphinx_docs.yml'
    pull_request:
        branches: master
        paths:
          - 'python/**'
          - '.github/workflows/python_sphinx_docs.yml'
    repository_dispatch:
      types: [docstrings_common_updated]
permissions:
    contents: write

jobs:
    build:
      runs-on: ubuntu-latest
      continue-on-error: true  # Do not fail the whole pipeline even if this job fails
      steps:
        - name: Checkout source code
          uses: actions/checkout@v4
          with:
            fetch-depth: 0   # Fetch all history for all tags and branches
        - name: Get docstrings_common.json from opm-common
          run: |
            curl -L -o python/docstrings_common.json https://raw.githubusercontent.com/${{ github.repository_owner }}/opm-common/master/python/docstrings_common.json
        - name: Set up Python
          uses: actions/setup-python@v5
          with:
            python-version: "3.11"
        - name: Install poetry
          uses: abatilo/actions-poetry@v2
        - name: Install python dependencies
          run: |
            cd python/sphinx_docs
            poetry install
        - name: Build documentation
          run: |
            cd python
            mkdir gh-pages
            touch gh-pages/.nojekyll
            cd sphinx_docs
            # Currently we build only docs for the HEAD of the master branch
            # Later we can add release tags to the list to get the docs for the releases
            # For example: -b "master, release/2024.04/final" will build the docs for
            # the master branch and the release/2024.04/final tag
            poetry run sphinx-versioned -m master -b master --force --git-root ../../
        - name: Copy documentation to gh-pages
          run: |
            cp -r python/sphinx_docs/docs/_build/* python/gh-pages/
        - name: Deploy documentation
          uses: JamesIves/github-pages-deploy-action@v4
          with:
            branch: gh-pages
            folder: python/gh-pages