From 852e9308cbd6e491e3f48049069d95cd6a511d9d 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 19:35:28 +0200
Subject: [PATCH] Fix documentation build system branch handling

This commit fixes how the documentation build system handles different branch types
during sphinx-versioned multi-version builds.

Changes:
1. conf.py: Fixed branch detection logic to properly distinguish between release
   branches (which have committed JSON snapshots) and all other branches (which
   use downloaded master JSON files). Also removed unused 'release' variable.

2. python_sphinx_docs.yml: Added comprehensive documentation explaining why JSON
   files are downloaded to master-tmp/ directory and how this supports multi-version
   documentation builds.

The previous logic incorrectly assumed only the master branch should use downloaded
files, causing development branches to fail when looking for non-existent committed
files. Now all non-release branches correctly use the downloaded master JSON files.
---
 .github/workflows/python_sphinx_docs.yml |  6 ++++++
 python/sphinx_docs/docs/conf.py          | 18 +++++++++++++-----
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/python_sphinx_docs.yml b/.github/workflows/python_sphinx_docs.yml
index ac4c9aa..46dc365 100644
--- a/.github/workflows/python_sphinx_docs.yml
+++ b/.github/workflows/python_sphinx_docs.yml
@@ -22,6 +22,12 @@ jobs:
         - 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
diff --git a/python/sphinx_docs/docs/conf.py b/python/sphinx_docs/docs/conf.py
index f888513..1948314 100644
--- a/python/sphinx_docs/docs/conf.py
+++ b/python/sphinx_docs/docs/conf.py
@@ -24,13 +24,21 @@ def extract_opm_simulators_release(version_file_path):
     except Exception:
         return "unknown"  # Fallback version
 
+# Determine JSON file location based on branch type
+# This prefix is used to set opm_simulators_docstrings_path and opm_common_docstrings_path below,
+# which are passed through Sphinx's config system to the sphinx_ext_docstrings extension.
+# The extension reads these paths to load JSON files and generate documentation.
+#
+# Branch handling for sphinx-versioned multi-version builds:
+# - Release branches (release-*): Use committed JSON snapshots in python/
+# - All other branches: Use downloaded master JSON files in python/master-tmp/
+#   This includes master itself and development branches, ensuring they all use
+#   the latest master JSON files without interfering with release snapshots.
 branch = get_git_branch()
-print(branch)
-if branch == "master":
-    prefix = "../../master-tmp"
-else:
+if branch.startswith("release-"):
     prefix = "../../"
-release = extract_opm_simulators_release(os.path.join(prefix, "dune.module"))
+else:
+    prefix = "../../master-tmp"
 
 # -- General configuration ---------------------------------------------------
 import sys