opm-python-documentation/.github/workflows/python_sphinx_docs.yml at master · OPM/opm-python-documentation · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
name: Build Python Sphinx Docs and push to gh-pages

on:
    push:
        branches:
          - '**'
    # Use pull_request (not pull_request_target) to build-test docs on PRs targeting master.
    # When a PR is merged, only the 'push' event triggers deployment to gh-pages.
    # Using pull_request_target here previously caused a race condition: merging a PR fired
    # both 'push' and 'pull_request_target' simultaneously, producing two concurrent runs
    # that both tried to force-push to gh-pages. The loser would fail with:
    #   "cannot lock ref 'refs/heads/gh-pages': is at <new-sha> but expected <old-sha>"
    # See: https://github.com/OPM/opm-python-documentation/actions/runs/21938360885
    pull_request:
        branches: [master]
    repository_dispatch:
      types: [docstrings_common_updated, docstrings_simulators_updated]
    # Manual trigger ("Run workflow" in the Actions tab). Use it to rebuild and republish
    # after a dispatch from opm-common or opm-simulators failed, e.g. because the token
    # those repositories send it with has expired. Run on master it deploys to gh-pages;
    # run on any other branch it only builds.
    workflow_dispatch:
permissions:
    contents: write
jobs:
    build:
      runs-on: ubuntu-latest
      steps:
        - name: Checkout source code
          uses: actions/checkout@v7
          with:
            fetch-depth: 0   # Fetch all history for all tags and branches
        - name: Create tmp directories for master
          run: |
            mkdir python/master-tmp
        # Download master JSON files to master-tmp/ directory
        # This supports sphinx-versioned multi-version documentation builds:
        # - sphinx-versioned builds docs for multiple branches (master, release-*, current branch)
        # - Each branch version looks for JSON files in different locations (see conf.py)
        # - master-tmp/ provides a shared location for current master JSON files that doesn't
        #   interfere with committed release snapshots in python/ directory
        - name: Get docstrings_common.json from master branch of opm-common
          run: |
            curl -L -o python/master-tmp/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/master-tmp/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, this is needed for the call to extract_opm_simulators_release in python/sphinx_docs/docs/conf.py.
          run: |
            curl -L -o python/master-tmp/dune.module https://raw.githubusercontent.com/OPM/opm-simulators/master/dune.module
        - name: Set up Python
          uses: actions/setup-python@v7
          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
            # To add a new release to this build system:
            # - add the respective branch <your-new-release> on this repository, replace the slashes "/" by dashes "-"
            #   (slashes mess with the navigation html created by sphinx-versioned)
            # - take a snapshot of https://raw.githubusercontent.com/OPM/opm-common/<your-new-release>/python/docstrings_common.json,
            #   https://raw.githubusercontent.com/OPM/opm-simulators/<your-new-release>/python/docstrings_simulators.json and
            #   https://raw.githubusercontent.com/OPM/opm-simulators/<your-new-release>/dune.module and put them
            #   in the python folder on that branch
            # Once created, the script below will automatically detect and include the new release branch

            # Dynamically determine which branches to build documentation for
            # This allows the workflow to work on forks that may not have all release branches
            # For pull_request events, github.ref_name is the merge ref (e.g. "21/merge"),
            # not a real branch. Use github.base_ref (the PR target branch, e.g. "master")
            # instead, falling back to github.ref_name for push/dispatch events where
            # github.base_ref is empty.
            BRANCHES=$(../scripts/get_doc_branches.sh "${{ github.base_ref || github.ref_name }}")
            echo "Building documentation for branches: $BRANCHES"
            poetry run sphinx-versioned -m master -b "$BRANCHES" --force --git-root ../../
        - 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' && !startsWith(github.ref, 'refs/heads/release')
          uses: OPM/github-pages-deploy-action@releases/v4
          with:
            branch: gh-pages-${{ github.ref_name }}
            folder: python/gh-pages