-
Notifications
You must be signed in to change notification settings - Fork 117
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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.
- Loading branch information
1 parent
2c4efcf
commit bd11093
Showing
13 changed files
with
794 additions
and
6 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 . | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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/", | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
Introduction | ||
============ | ||
|
||
Documentation for the ``opm.simulators`` Python module. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
Python Module Documentation | ||
=========================== | ||
|
||
.. opm_simulators_docstrings:: |
Oops, something went wrong.