Development setup#

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

python -m venv .venv
source .venv/bin/activate
pip install -e ".[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 checkout direnv.

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

Using make for shortcuts!

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:

help              Show this help
setup             Setup a virtual environment and install all development dependencies
setup_headless    Install vtk-osmesa and gmsh without X11 dependencies
test              Runs the unit tests
coverage          Runs the unit tests generating code coverage reports
check             Runs various checks with pre-commit
clean             Cleans up temporary files
docs              Builds the documentation
cleandocs         Cleans up temporary documentation files
preview           Runs an auto-updating web server for the documentation

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.

Further information#

For syntax references and extension usage see the following links:

Run checks#

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

pre-commit run --all-files

Testing with `tox`#

To test for different Python version you can use tox.

To run the tests:

tox

Note

You can parallelize the tox tests with tox -p.

You can also run a single test environment with e.g.:

tox -e py39

The following environments are available:

$ tox list
default environments:
py39       -> Run tests with py39
py310      -> Run tests with py310
py311      -> Run tests with py311
report     -> Combines coverage reports into html and xml reports.
pre-commit -> Run pre-commit on all files

additional environments:
docs       -> Create documentation
publish    -> Run tests with publish
pragma     -> Run tests with pragma

Create a package#

pyproject-build

Packages can then be found in dist/.