From 048f50e9082df55cf1d88db5dae49fb95ebdd73c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?H=C3=A5kon=20H=C3=A6gland?= <hakon.hagland@gmail.com>
Date: Fri, 22 Aug 2025 20:03:56 +0200
Subject: [PATCH] Make documentation workflow fork-friendly with dynamic branch
 detection

This commit makes the Sphinx documentation build workflow work seamlessly on
forks that may not have all release branches available.

Changes:
1. Added python/scripts/get_doc_branches.sh script that dynamically detects
   available branches (current, master, release-*) in the repository

2. Updated python_sphinx_docs.yml to use the script instead of hardcoded
   branch lists, removing the need for manual edits when testing on forks

3. Clarified comment to distinguish between manual release branch creation
   and automatic branch detection

Benefits:
- Workflow automatically adapts to available branches in any fork
- No manual edits needed for testing in development forks
- Gracefully handles missing release branches
- Automatically includes new release branches as they're added

The script checks for remote branches to ensure it works properly with both
the main repository (which has all branches) and forks (which may only have
a subset).
---
 .github/workflows/python_sphinx_docs.yml | 15 +++++-----
 python/scripts/get_doc_branches.sh       | 38 ++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 7 deletions(-)
 create mode 100755 python/scripts/get_doc_branches.sh

diff --git a/.github/workflows/python_sphinx_docs.yml b/.github/workflows/python_sphinx_docs.yml
index ac4c9aa..8db9a5f 100644
--- a/.github/workflows/python_sphinx_docs.yml
+++ b/.github/workflows/python_sphinx_docs.yml
@@ -47,19 +47,20 @@ jobs:
             mkdir gh-pages
             touch gh-pages/.nojekyll
             cd sphinx_docs
-            # To add a new relase to this build system:
+            # 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
-            # - add the respective branch <your-new-release> in the command below
-            if [ "${{ github.ref_name }}" == "master" ]; then
-              poetry run sphinx-versioned -m master -b "master release-2025.04" --force --git-root ../../
-            else
-              poetry run sphinx-versioned -m master -b "${{ github.ref_name }} master release-2025.04" --force --git-root ../../
-            fi
+            # 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
+            BRANCHES=$(../scripts/get_doc_branches.sh "${{ 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
diff --git a/python/scripts/get_doc_branches.sh b/python/scripts/get_doc_branches.sh
new file mode 100755
index 0000000..a6c3dc4
--- /dev/null
+++ b/python/scripts/get_doc_branches.sh
@@ -0,0 +1,38 @@
+#!/bin/bash
+# Script to dynamically determine which branches to build documentation for
+# This makes the workflow work on forks that may not have all release branches
+#
+# Usage: get_doc_branches.sh <current_branch_name>
+#
+# Returns: Space-separated list of branches for sphinx-versioned
+
+set -e
+
+CURRENT_BRANCH="$1"
+
+if [ -z "$CURRENT_BRANCH" ]; then
+    echo "Error: Current branch name must be provided as first argument" >&2
+    exit 1
+fi
+
+# Initialize branch list with current branch
+BRANCHES="$CURRENT_BRANCH"
+
+# Add master if it exists and isn't already in the list
+if git ls-remote --heads origin master >/dev/null 2>&1; then
+    if [ "$CURRENT_BRANCH" != "master" ]; then
+        BRANCHES="$BRANCHES master"
+    fi
+fi
+
+# Add all release branches that exist
+# Note: We check for remote branches to handle forks properly
+for branch in $(git ls-remote --heads origin | grep -E 'refs/heads/release-' | sed 's/.*refs\/heads\///'); do
+    # Skip if already in list (shouldn't happen with release branches, but be safe)
+    if [[ ! " $BRANCHES " =~ " $branch " ]]; then
+        BRANCHES="$BRANCHES $branch"
+    fi
+done
+
+# Output the branch list
+echo "$BRANCHES"
\ No newline at end of file