Added sphinx documentation for Python bindings

Added sphinx documentation for the opm.simulators.BlackOilSimulator
Python module. Added GitHub action workflow to deploy sphinx
documentation to GitHub Pages.

.github/workflows/python_sphinx_docs.yml

@@ -0,0 +1,48 @@
+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@v3
+        - 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/docs/
+            poetry run sphinx-build -b html . _build
+        - name: Copy documentation to gh-pages
+          run: |
+            cd python/sphinx_docs/docs
+            cp -r _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/docstrings.json

@@ -29,23 +29,23 @@
     },
     "getFluidStateVariables": {
         "signature": "get_fluid_state_variables(name: str) -> NDArray[float]",
-        "doc": "Retrieve a fluid state variable for the simulation grid.\n\n:para name: The name of the variable. Valid names are 'pw' (pressure water), 'pg' (pressure gas), 'po' (pressure oil), 'rho_w' (density water), 'rho_g' (density gas), 'rho_o' (density oil)'Rs' (soultion gas-oil ratio), 'Rv' (volatile gas-oil ratio), 'Sw' (water saturation), 'Sg' (gas saturation), 'So' (oil saturation), and 'T' (temperature).\n:type name: str\n\n:return: An array of fluid state variables.\n:type return: NDArray[float]"
+        "doc": "Retrieve a fluid state variable for the simulation grid.\n\n:param name: The name of the variable. Valid names are 'pw' (pressure water), 'pg' (pressure gas), 'po' (pressure oil), 'rho_w' (density water), 'rho_g' (density gas), 'rho_o' (density oil)'Rs' (soultion gas-oil ratio), 'Rv' (volatile gas-oil ratio), 'Sw' (water saturation), 'Sg' (gas saturation), 'So' (oil saturation), and 'T' (temperature).\n:type name: str\n\n:return: An array of fluid state variables.\n:type return: NDArray[float]"
     },
     "getPorosity": {
         "signature": "get_porosity() -> numpy.ndarray",
         "doc": "Retrieve the porosity values of the simulation grid.\n\n:return: An array of porosity values.\n:type return: numpy.ndarray"
     },
     "getPrimaryVarMeaning": {
         "signature": "get_primary_var_meaning(variable: str) -> NDArray[int]",
-        "doc": "Retrieve the primary variable meaning of the simulation grid.\n\n:para variable: The name of the variable. Valid names are 'pressure', 'water', 'gas', and 'brine'.\n:type variable: str\n\n:return: An array of primary variable meanings. See ``get_primary_variable_meaning_map()`` for more information.\n:type return: NDArray[int]"
+        "doc": "Retrieve the primary variable meaning of the simulation grid.\n\n:param variable: The name of the variable. Valid names are 'pressure', 'water', 'gas', and 'brine'.\n:type variable: str\n\n:return: An array of primary variable meanings. See ``get_primary_variable_meaning_map()`` for more information.\n:type return: NDArray[int]"
     },
     "getPrimaryVarMeaningMap": {
         "signature": "get_primary_var_meaning_map(variable: str) -> dict[str, int]",
-        "doc": "Retrieve the primary variable meaning map for each primary variable.\n\n:para variable: The name of the variable. Valid names are 'pressure', 'water', 'gas', and 'brine'.\n:type variable: str\n\n:return: A dictionary of primary variable meanings. The keys are the primary variable meanings and the values are the corresponding integer codes. The integer codes are used to represent the primary variable meanings in the simulation grid. For variable name 'pressure', the valid keys are: 'Po', 'Pg', and 'Pw', for variable name 'water', the valid keys are: 'Sw', 'Rvw', 'Rsw', and 'Disabled', for variable name 'gas', the valid keys are: 'Sg', 'Rs', 'Rv', and 'Disabled', for variable name 'brine', the valid keys are: 'Cs', 'Sp', and 'Disabled'.\n:type return: dict[str, int]"
+        "doc": "Retrieve the primary variable meaning map for each primary variable.\n\n:param variable: The name of the variable. Valid names are 'pressure', 'water', 'gas', and 'brine'.\n:type variable: str\n\n:return: A dictionary of primary variable meanings. The keys are the primary variable meanings and the values are the corresponding integer codes. The integer codes are used to represent the primary variable meanings in the simulation grid. For variable name 'pressure', the valid keys are: 'Po', 'Pg', and 'Pw', for variable name 'water', the valid keys are: 'Sw', 'Rvw', 'Rsw', and 'Disabled', for variable name 'gas', the valid keys are: 'Sg', 'Rs', 'Rv', and 'Disabled', for variable name 'brine', the valid keys are: 'Cs', 'Sp', and 'Disabled'.\n:type return: dict[str, int]"
     },
     "getPrimaryVariable": {
         "signature": "get_primary_variable(variable: str) -> NDArray[float]",
-        "doc": "Retrieve the primary variable's values for the simulation grid.\n\n:para variable: The name of the variable. Valid names are 'pressure', 'water', 'gas', and 'brine'.\n:type variable: str\n\n:return: An array of primary variable values. See ``get_primary_variable_meaning()`` for more information.\n:type return: NDArray[float]"
+        "doc": "Retrieve the primary variable's values for the simulation grid.\n\n:param variable: The name of the variable. Valid names are 'pressure', 'water', 'gas', and 'brine'.\n:type variable: str\n\n:return: An array of primary variable values. See ``get_primary_variable_meaning()`` for more information.\n:type return: NDArray[float]"
     },
     "run": {
         "signature": "run() -> int",
@@ -57,7 +57,7 @@
     },
     "setPrimaryVariable": {
         "signature": "set_primary_variable(variable: str, value: NDArray[float]) -> None",
-        "doc": "Set the primary variable's values for the simulation grid.\n\n:para variable: The name of the variable. Valid names are 'pressure', 'water', 'gas', and 'brine'.\n:type variable: str\n:para value: An array of primary variable values to be set. See ``get_primary_variable()`` for more information.\n:type value: NDArray[float]"
+        "doc": "Set the primary variable's values for the simulation grid.\n\n:param variable: The name of the variable. Valid names are 'pressure', 'water', 'gas', and 'brine'.\n:type variable: str\n:param value: An array of primary variable values to be set. See ``get_primary_variable()`` for more information.\n:type value: NDArray[float]"
     },
     "step": {
         "signature": "step() -> int",

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/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

python/sphinx_docs/docs/conf.py

@@ -0,0 +1,44 @@
+# Configuration file for the Sphinx documentation builder.
+
+project = "opm.simulators"
+copyright = "2024 Equinor ASA"
+author = "Håkon Hægland"
+release = "0.1"
+
+# -- 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/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

python/sphinx_docs/docs/python.rst

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