Change build system such that it can build for more branches than master and do not push to a gh-pages branch if the branch starts with 'release'

Author: Lisa Julia Nebel

.github/workflows/python_sphinx_docs.yml

@@ -19,15 +19,18 @@ jobs:
           uses: actions/checkout@v4
           with:
             fetch-depth: 0   # Fetch all history for all tags and branches
+        - name: Create tmp directories for master
+          run: |
+            mkdir python/master-tmp
         - 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
+            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/docstrings_simulators.json https://raw.githubusercontent.com/OPM/opm-simulators/master/python/docstrings_simulators.json
+            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 dune.module https://raw.githubusercontent.com/OPM/opm-simulators/master/dune.module
+            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@v5
           with:
@@ -44,18 +47,18 @@ jobs:
             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
-
+            # To add a new relase 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" --force --git-root ../../
+              poetry run sphinx-versioned -m master -b "master release-2025.04" --force --git-root ../../
             else
-              poetry run sphinx-versioned -m master -b "master ${{ github.ref_name }}" --force --git-root ../../
+              poetry run sphinx-versioned -m master -b "${{ github.ref_name }} master release-2025.04" --force --git-root ../../
             fi
         - name: Copy documentation to gh-pages
           run: |
@@ -68,7 +71,7 @@ jobs:
             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'
+          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 }}

.gitignore

@@ -1,7 +1,5 @@
 # Files necessary to build the documentation locally, but these are tracked by other github repositories
-/dune.module
-python/docstrings_common.json
-python/docstrings_simulators.json
+python/master-tmp
 
 # Python sphinx build
 python/sphinx_docs/docs/_build*

README.md

@@ -11,6 +11,7 @@ See also the script [opmdoc-download-files](https://github.com/OPM/opm-python-do
 
 ## Building the documentation online on your fork
 - Turn on github actions at `https://github.com/<your-github-username>/opm-python-documentation/actions`
+- Add the docstrings_common.json and docstrings_simulators.json file you want to test to the python folder
 - Push any changes to a branch of your fork, this should trigger a build of the documentation, where the built documentation is pushed to the branch `gh-pages-<name-of-your-branch>`
 - Then you can turn on github pages for your fork at `https://github.com/<your-github-username>/opm-python-documentation/settings/pages`
 - Select the branch `gh-pages-<name-of-your-branch>` as the source for your github page

python/sphinx_docs/docs/conf.py

@@ -1,23 +1,38 @@
 # Configuration file for the Sphinx documentation builder.
 
+import os
+import subprocess
+
 project = "OPM Python Documentation"
 copyright = "2024 Equinor ASA"
 author = "Håkon Hægland"
 
+def get_git_branch():
+    try:
+        return subprocess.check_output(["git", "rev-parse", "--abbrev-ref", "HEAD"]).decode("utf-8").strip()
+    except Exception:
+        return "unknown"
+
 # Function to extract release version from dune.module file
-def extract_opm_simulators_release():
-    version_file_path = '../../../dune.module'
-    with open(version_file_path, 'r') as file:
-        for line in file:
-            if line.startswith('Version:'):
-                version_string = line.split(':')[1].strip()
-                return version_string
-    return "unknown"  # Fallback version
+def extract_opm_simulators_release(version_file_path):
+    try:
+        with open(version_file_path, 'r') as file:
+            for line in file:
+                if line.startswith('Version:'):
+                    version_string = line.split(':')[1].strip()
+                    return version_string
+    except Exception:
+        return "unknown"  # Fallback version
 
-release = extract_opm_simulators_release()
+branch = get_git_branch()
+print(branch)
+if branch == "master":
+    prefix = "../../master-tmp"
+else:
+    prefix = "../../"
+release = extract_opm_simulators_release(os.path.join(prefix, "dune.module"))
 
 # -- General configuration ---------------------------------------------------
-import os
 import sys
 
 # For regular Python packages, the path to the package is usually added to sys.path
@@ -35,9 +50,10 @@ def extract_opm_simulators_release():
 sys.path.insert(0, os.path.abspath("../src"))
 # Our sphinx extension that will use the docstrings.json file to generate documentation
 extensions = ["opm_python_docs.sphinx_ext_docstrings"]
+
 # Path to docstrings.json
-opm_simulators_docstrings_path = os.path.abspath('../../docstrings_simulators.json')
-opm_common_docstrings_path = os.path.abspath('../../docstrings_common.json')
+opm_simulators_docstrings_path = os.path.abspath(os.path.join(prefix, "docstrings_simulators.json"))
+opm_common_docstrings_path = os.path.abspath(os.path.join(prefix, "docstrings_common.json"))
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]