index.md

Development setup

Cloning the Source Repository

You can clone the source repository from https://gitlab.opengeosys.org/ogs/tools/ogstools and install the latest version by running:

git clone git@gitlab.opengeosys.org:ogs/tools/ogstools.git or git clone https://gitlab.opengeosys.org/ogs/tools/ogstools.git

Development environment

Change into the directory with the cloned ogstools sources. (. assumes that your working directory contains the ogstools sources, the directory where you find the pyproject.toml).

cd ogstools

Create a virtual environment, activate it and install required packages:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[pinned,dev,test,docs]"

# enable basic style checks once
pre-commit install

:::{important} Make sure to activate the virtual environment in every new shell session:

source .venv/bin/activate

If you want to automate this install direnv and allow it once via direnv allow (see .envrc configuration file).

Windows-specifics

On Windows the syntax for virtual environment activation is a bit different:

# The following may need to be run once. Please check the docs for its consequences:
# https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policiess
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

# Activate via:
.venv\Scripts\Activate.ps1

:::

CLI scripts can now be simply run:

msh2vtu --help

:::{admonition} Using make for shortcuts! :class: tip :name: make-shortcut

Development-related tasks can also be done with make (requires a Bash shell with make). The above development setup can also be generated with:

make setup

To get all available make-targets run make help:

:::

Testing with pytest

Tests are executed via pytest (shortcut: make test):

pytest [--capture=tee-sys]

Test coverage

The following commands run the tests and create a test coverage report (shortcut: make coverage):

coverage run -m pytest
coverage combine
coverage report --no-skip-covered
coverage html
...
TOTAL                                                                  1698    292    83%
coverage html
Wrote HTML report to htmlcov/index.html

You can view a test coverage report by opening htmlcov/index.html in a browser.

Build documentation

For generating the documentation we use Sphinx (shortcut: make docs):

cd docs
make html

This will create the documentation files in docs/_build/html.

You can use an auto-generating and -reloading web server (Linux / macOS only) for developing the documentation (shortcut: make preview):

make html -C docs # Generate docs once
python docs/server.py
# Open http://127.0.0.1:5500 in a web browser
# ...
# You can stop the server in the terminal with CTRL-D

Galleries

Python files in docs/examples will be added to the Examples-gallery based on sphinx-gallery. Please note that text blocks are written reStructuredText-format. The examples can be downloaded from the final website as Jupyter notebook files.

You can interactively run and debug these files in Visual Studio Code, see the Python Interactive window documentation.

If you want to link to a gallery page from another page use the following syntax (prefix with sphx_glr_, replace directory separator with _):

{ref}`meshlib example <sphx_glr_auto_examples_howto_meshlib_plot_meshlib_pyvista_input.py>`

Guidelines for examples

In order to maintain consistency in style and structure between different examples, please follow those recommendations when creating a new one:

• All imports and global settings must be done in first python block.
• No heading for import and settings cell.
• Examples that cover multiple steps and/or datasets must contain section.
• Sections have to be give a title, indicated by highest level heading.
• Section titles cannot start with ordinal number or letter (no 1./I./A. Example section title)

Further information

For syntax references and extension usage see the following links:

• Sphinx
• MyST Markdown Parser
• MySt Markdown cheat sheet
• PyData theme
• programoutput-extension
• sphinx_design-extension
• sphinx-gallery

Run checks

We use pre-commit to run various checks (shortcut make check):

pre-commit run --all-files

Create a package

pyproject-build

Packages can then be found in dist/.

Development in a container with VSCode

A full-featured (including e.g. FEFLOW-functionality), ready-to-use development environment can be used via VSCode's Dev Container feature. You can do all development-related tasks with it, e.g. testing, previewing documentation or even debugging.

Requirements

• Docker
• VSCode with Remote Development extension pack installed

How-to

• Open the ogstools-project in VSCode
• Click the blue button in the left-bottom corner
• Click on Reopen in Container