Add sphinx documentation for Python bindings and GitHub action workflow to push to GitHub pages

.github/workflows/python_sphinx_docs.yml

@@ -0,0 +1,53 @@
+name: Build Python Sphinx Docs and push to gh-pages
+
+on:
+    push:
+        branches: main
+        paths:
+          - 'python/**'
+          - '.github/workflows/python_sphinx_docs.yml'
+    pull_request:
+        branches: main
+        paths:
+          - 'python/**'
+          - '.github/workflows/python_sphinx_docs.yml'
+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: Set up Python
+          uses: actions/setup-python@v4
+          with:
+            python-version: "3.11"
+        - name: Install poetry
+          uses: abatilo/actions-poetry@v2
+        - 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 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
+            poetry run sphinx-versioned -m master -b master --git-root ../../
+        - name: Copy documentation to gh-pages
+          run: |
+            cp -r python/sphinx_docs/docs/_build/* gh-pages/
+        - name: Deploy documentation
+          if: ${{ github.event_name == 'push' }}
+          uses: JamesIves/github-pages-deploy-action@v4
+          with:
+            branch: gh-pages
+            folder: python/gh-pages

.gitignore

@@ -34,4 +34,11 @@ build/
 *.dSYM
 
 # emacs directory setting:
-.dir-locals.el
+.dir-locals.el
+
+# Python sphinx build
+python/sphinx_docs/docs/_build/
+
+# Python cache directories
+**/__pycache__/
+

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/conf.py

@@ -0,0 +1,55 @@
+# Configuration file for the Sphinx documentation builder.
+
+project = "opm.simulators"
+copyright = "2024 Equinor ASA"
+author = "Håkon Hægland"
+
+# 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
+
+release = extract_opm_simulators_release()
+
+# -- General configuration ---------------------------------------------------
+import os
+import sys
+
+# For regular Python packages, the path to the package is usually added to sys.path
+# here such that autodoc can find the modules. However, our Python module
+#  opm.simulators.BlackOilSimulator is not generated yet. Since it is a pybind11
+# extension module, it needs to be compiled as part of the opm-simulators build
+# process (which requires building opm-common first and so on). The full compilation
+# of opm-simulators requres time and storage resources, so we do not want to
+# do this as part of the documentation build. Instead, we will use a sphinx extension
+# (Python script) to generate documentation from a JSON input file. (This JSON file
+# is also is also used to generate a C++ header file with docstrings. The header file
+# is generated when opm-simulators is built and is then included
+# in the pybind11 binding code for the BlackOilSimulator class. In this way, the
+# opm.simulators.BlackOilSimulator Python module will also have access to the docstrings.)
+sys.path.insert(0, os.path.abspath("../src"))
+# Our sphinx extension that will use the docstrings.json file to generate documentation
+extensions = ["opm_simulators_docs.sphinx_ext_docstrings"]
+# Path to docstrings.json
+opm_simulators_docstrings_path = os.path.abspath('../../docstrings.json')
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# See: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_context = {
+    "display_github": True,
+    "github_user": "OPM",
+    "github_repo": "opm-simulators",
+    "github_version": "master",
+    "conf_py_path": "/python/docs/",
+}

python/sphinx_docs/docs/index.rst

@@ -0,0 +1,16 @@
+Welcome to the Python documentation for opm-simulators!
+=======================================================
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Contents:
+
+    introduction
+    python
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

python/sphinx_docs/docs/introduction.rst

@@ -0,0 +1,4 @@
+Introduction
+============
+
+Documentation for the ``opm.simulators`` Python module.

python/sphinx_docs/docs/python.rst

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