python_sphinx_docs.yml

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

on:
    push:
        branches:
          - '**'
    pull_request_target:
        types: closed
        branches: master
    repository_dispatch:
      types: [docstrings_common_updated, docstrings_simulators_updated]
permissions:
    contents: write
jobs:
    build:
      runs-on: ubuntu-latest
      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 master branch of opm-common
          run: |
            curl -L -o python/docstrings_common.json https://raw.githubusercontent.com/OPM/opm-common/master/python/docstrings_common.json
        - name: Get docstrings_common.json from master branch of opm-simulators
          run: |
            curl -L -o python/docstrings_simulators.json https://raw.githubusercontent.com/OPM/opm-simulators/master/python/docstrings_simulators.json
        - name: Get dune.module from master branch of opm-simulators
          run: |
            curl -L -o dune.module https://raw.githubusercontent.com/OPM/opm-simulators/master/dune.module
        - name: Set up Python
          uses: actions/setup-python@v5
          with:
            python-version: "3.11"
        - name: Install poetry
          uses: OPM/actions-poetry@master
        - 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
            # For the releases, we create snapshots of the docstrings_common.json and docstrings_simulators.json
            # and take the ones tracked by git, only for the master, we take the current ones we fetched
            # in steps 2 and 3 of this workflow

            if [ "${{ github.ref_name }}" == "master" ]; then
              poetry run sphinx-versioned -m master -b "master" --force --git-root ../../
            else
              poetry run sphinx-versioned -m master -b "master ${{ github.ref_name }}" --force --git-root ../../
            fi
        - name: Copy documentation to gh-pages
          run: |
            cp -r python/sphinx_docs/docs/_build/* python/gh-pages

        - name: Deploy documentation for PR merge to master or push to master
          if: github.ref == 'refs/heads/master'
          uses: OPM/github-pages-deploy-action@releases/v4
          with:
            branch: gh-pages
            folder: python/gh-pages
        - name: Deploy documentation for other branches (on forks)
          if: github.event_name == 'push' && github.ref != 'refs/heads/master'
          uses: OPM/github-pages-deploy-action@releases/v4
          with:
            branch: gh-pages-${{ github.ref_name }}
            folder: python/gh-pages