Move python documentation things from opm-simulators to here

.github/workflows/python_sphinx_docs.yml

@@ -0,0 +1,77 @@
+name: Build Python Sphinx Docs and push to gh-pages
+
+on:
+    push:
+        branches:
+          - '**'
+        paths:
+          - 'python/sphinx_docs/**'
+    pull_request_target:
+        types: closed
+        branches: main
+        paths:
+          - 'python/sphinx_docs/**'
+    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/${{ github.repository_owner }}/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/${{ github.repository_owner }}/opm-simulators/master/python/docstrings_simulators.json
+        - 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/main branch
+            # Later we can add release tags to the list to get the docs for the releases
+            # For example: -b "main, release/2024.04/final" will build the docs for
+            # the main 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 main, we take the current ones we fetched
+            # in steps 2 and 3 of this workflow
+
+            # If this is a build for main, then the build the documentation for the main branch
+            if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+              branch=main
+            else
+              branch=${{ github.ref }}
+            fi
+            poetry run sphinx-versioned -m main -b "${branch}" --force --git-root ../../
+        - name: Copy documentation to gh-pages
+          run: |
+            cp -r python/sphinx_docs/docs/_build/* python/gh-pages-${{ github.ref }}/
+        - name: Deploy documentation for PR merge to main or push to main
+          if: github.ref == 'refs/heads/main'
+          uses: OPM/github-pages-deploy-action@releases/v4
+          with:
+            branch: gh-pages
+            folder: python/gh-pages
+        - name: Deploy documentation for PRs and other branches
+          if: github.event_name == 'push' && github.ref != 'refs/heads/main'
+          uses: OPM/github-pages-deploy-action@releases/v4
+          with:
+            branch: gh-pages-${{ github.ref }}
+            folder: python/gh-pages-${{ github.ref }}   

python/sphinx_docs/Makefile

@@ -0,0 +1,7 @@
+.PHONY: docs
+
+# Build the documentation locally for the current branch
+# NOTE: You need to commit your changes before running this command
+docs:
+	@CURRENT_BRANCH=$(shell git rev-parse --abbrev-ref HEAD)
+	sphinx-versioned -m $$CURRENT_BRANCH -b $$CURRENT_BRANCH --git-root ../../

python/sphinx_docs/README.md

@@ -0,0 +1,23 @@
+# Python scripts for building opm-simulators sphinx documentation
+
+## Installation of the python scripts
+- Requires python3 >= 3.10
+
+### Using poetry
+For development it is recommended to use poetry:
+
+- Install [poetry](https://python-poetry.org/docs/)
+- Then run:
+```
+$ poetry install
+$ poetry shell
+```
+
+### Installation into virtual environment
+If you do not plan to change the code, you can do a regular installation into a VENV:
+
+```
+$ python -m venv .venv
+$ source .venv/bin/activate
+$ pip install .
+```

python/sphinx_docs/docs/_build/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 8ae7c4b8ba63d86e73aec85425c18620
+tags: 645f666f9bcd5a90fca523b33c5a78b7

python/sphinx_docs/docs/_build/_sources/common.rst.txt

@@ -0,0 +1,4 @@
+OPM Common Python Documentation
+===============================
+
+.. opm_common_docstrings::

python/sphinx_docs/docs/_build/_sources/embedded.rst.txt

@@ -0,0 +1,52 @@
+OPM Embedded Python Documentation
+=================================
+
+The PYACTION keyword is a flow specific keyword which allows for executing embedded Python
+code in the SCHEDULE section. The embedded Python code will then be executed at the end of each successful timestep.
+
+The PYACTION keyword is inspired
+by the ACTIONX keyword, but instead of a .DATA formatted condition you
+are allowed to implement the condition with a general Python script. The
+ACTIONX keywords are very clearly separated in a condition part and an
+action part in the form of a list of keywords which are effectively injected in
+the SCHEDULE section when the condition evaluates to true.
+This is not so for PYACTION where there is one Python script in which both
+conditions can be evaluated and changes applied.
+
+In order to enable the PYACTION keyword:
+
+1. OPM flow must be compiled with the cmake switches -DOPM ENABLE EMBEDDED PYTHON=ON and -DOPM ENABLE PYTHON=ON, the default is to build with these switches set to OFF.
+
+2. The keyword PYACTION must be added to the SCHEDULE section:
+
+.. code-block:: python
+
+	<PYACTION\_NAME>  <SINGLE/UNLIMITED> /
+	<pythonscript> /
+
+3. You need to provide the Python script.
+
+
+To interact with the simulator in the embedded Python code, you can access four variables from the simulator:
+
+.. code-block:: python
+
+	# Python module opm_embedded
+	import opm_embedded
+	# The current EclipseState
+	ecl_state = opm_embedded.current_ecl_state
+	# The current Schedule
+	schedule = opm_embedded.current_schedule
+	# The current SummaryState
+	summary_state = opm_embedded.current_summary_state
+	# The current report step
+	report_step = opm_embedded.current_report_step 
+
+
+- current_ecl_state: An instance of the `EclipseState <common.html#opm.io.ecl_state.EclipseState>`_ class - this is a representation of all static properties in the model, ranging from porosity to relperm tables. The content of the ecl state is immutable - you are not allowed to change the static properties at runtime.
+
+- current_schedule: An instance of the `Schedule <common.html#opm.io.schedule.Schedule>`_ class - this is a representation of all the content from the SCHEDULE section, notably all well and group information and the timestepping.
+
+- current_report_step: This is an integer for the report step we are currently working on. Observe that the PYACTION is called for every simulator timestep, i.e. it will typically be called multiple times with the same value for the report step argument.
+
+- current_summary_state: An instance of the `SummaryState <common.html#opm.io.sim.SummaryState>`_ class, this is where the current summary results of the simulator are stored. The SummaryState class has methods to get hold of well, group and general variables.

python/sphinx_docs/docs/_build/_sources/index.rst.txt

@@ -0,0 +1,18 @@
+Welcome to the Python documentation for OPM Flow!
+=================================================
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Contents:
+
+    introduction
+    common
+    simulators
+    embedded
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

python/sphinx_docs/docs/_build/_sources/introduction.rst.txt

@@ -0,0 +1,4 @@
+Introduction
+============
+
+Documentation for the OPM Python interfaces.

python/sphinx_docs/docs/_build/_sources/simulators.rst.txt

@@ -0,0 +1,4 @@
+OPM Simulators Python Documentation
+===================================
+
+.. opm_simulators_docstrings::

python/sphinx_docs/docs/_build/_static/_sphinx_javascript_frameworks_compat.js

@@ -0,0 +1,123 @@
+/* Compatability shim for jQuery and underscores.js.
+ *
+ * Copyright Sphinx contributors
+ * Released under the two clause BSD licence
+ */
+
+/**
+ * small helper function to urldecode strings
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
+ */
+jQuery.urldecode = function(x) {
+    if (!x) {
+        return x
+    }
+    return decodeURIComponent(x.replace(/\+/g, ' '));
+};
+
+/**
+ * small helper function to urlencode strings
+ */
+jQuery.urlencode = encodeURIComponent;
+
+/**
+ * This function returns the parsed url parameters of the
+ * current request. Multiple values per key are supported,
+ * it will always return arrays of strings for the value parts.
+ */
+jQuery.getQueryParameters = function(s) {
+    if (typeof s === 'undefined')
+        s = document.location.search;
+    var parts = s.substr(s.indexOf('?') + 1).split('&');
+    var result = {};
+    for (var i = 0; i < parts.length; i++) {
+        var tmp = parts[i].split('=', 2);
+        var key = jQuery.urldecode(tmp[0]);
+        var value = jQuery.urldecode(tmp[1]);
+        if (key in result)
+            result[key].push(value);
+        else
+            result[key] = [value];
+    }
+    return result;
+};
+
+/**
+ * highlight a given string on a jquery object by wrapping it in
+ * span elements with the given class name.
+ */
+jQuery.fn.highlightText = function(text, className) {
+    function highlight(node, addItems) {
+        if (node.nodeType === 3) {
+            var val = node.nodeValue;
+            var pos = val.toLowerCase().indexOf(text);
+            if (pos >= 0 &&
+                !jQuery(node.parentNode).hasClass(className) &&
+                !jQuery(node.parentNode).hasClass("nohighlight")) {
+                var span;
+                var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
+                if (isInSVG) {
+                    span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+                } else {
+                    span = document.createElement("span");
+                    span.className = className;
+                }
+                span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+                node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+                    document.createTextNode(val.substr(pos + text.length)),
+                    node.nextSibling));
+                node.nodeValue = val.substr(0, pos);
+                if (isInSVG) {
+                    var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+                    var bbox = node.parentElement.getBBox();
+                    rect.x.baseVal.value = bbox.x;
+                    rect.y.baseVal.value = bbox.y;
+                    rect.width.baseVal.value = bbox.width;
+                    rect.height.baseVal.value = bbox.height;
+                    rect.setAttribute('class', className);
+                    addItems.push({
+                        "parent": node.parentNode,
+                        "target": rect});
+                }
+            }
+        }
+        else if (!jQuery(node).is("button, select, textarea")) {
+            jQuery.each(node.childNodes, function() {
+                highlight(this, addItems);
+            });
+        }
+    }
+    var addItems = [];
+    var result = this.each(function() {
+        highlight(this, addItems);
+    });
+    for (var i = 0; i < addItems.length; ++i) {
+        jQuery(addItems[i].parent).before(addItems[i].target);
+    }
+    return result;
+};
+
+/*
+ * backward compatibility for jQuery.browser
+ * This will be supported until firefox bug is fixed.
+ */
+if (!jQuery.browser) {
+    jQuery.uaMatch = function(ua) {
+        ua = ua.toLowerCase();
+
+        var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
+            /(webkit)[ \/]([\w.]+)/.exec(ua) ||
+            /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
+            /(msie) ([\w.]+)/.exec(ua) ||
+            ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
+            [];
+
+        return {
+            browser: match[ 1 ] || "",
+            version: match[ 2 ] || "0"
+        };
+    };
+    jQuery.browser = {};
+    jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
+}