From b741b4074d6adf890680fbb1a35e9eed45bf468c Mon Sep 17 00:00:00 2001
From: Lars Bilke <lars.bilke@ufz.de>
Date: Thu, 14 Sep 2023 11:44:28 +0200
Subject: [PATCH] Added docs on devcontainer.
---
Makefile | 6 ++---
docs/development/index.md | 49 +++++++++++++++++++++++++++++++++++++++
2 files changed, 51 insertions(+), 4 deletions(-)
diff --git a/Makefile b/Makefile
index a01acb81d..fafd8e1d9 100644
--- a/Makefile
+++ b/Makefile
@@ -16,15 +16,13 @@ setup_headless: ## Install vtk-osmesa and gmsh without X11 dependencies
.venv/bin/pip install --extra-index-url https://wheels.vtk.org vtk-osmesa
.venv/bin/pip install -i https://gmsh.info/python-packages-dev-nox gmsh
-setup_devcontainer:
+setup_devcontainer: ## Internal usage
+ rm -rf .venv-devcontainer
python -m venv .venv-devcontainer --upgrade-deps
.venv-devcontainer/bin/pip install -e .[dev,test,docs,feflow]
.venv-devcontainer/bin/pip uninstall gmsh vtk -y
.venv-devcontainer/bin/pip install --extra-index-url https://wheels.vtk.org vtk-osmesa
.venv-devcontainer/bin/pip install -i https://gmsh.info/python-packages-dev-nox gmsh
- @echo
- @echo ATTENTION: You need to activate the virtual environment in every shell with:
- @echo source .venv-devcontainer/bin/activate
test: ## Runs the unit tests
pytest
diff --git a/docs/development/index.md b/docs/development/index.md
index 63003f041..06607bc17 100644
--- a/docs/development/index.md
+++ b/docs/development/index.md
@@ -170,3 +170,52 @@ 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](https://code.visualstudio.com/docs/devcontainers/containers) feature. You can do all development-related tasks with it, e.g. testing, previewing documentation or even debugging.
+
+## Requirements
+
+- [Docker](https://www.docker.com)
+- [VSCode](https://code.visualstudio.com/) with [Remote Development extension pack](https://code.visualstudio.com/docs/remote/remote-overview) installed
+
+## How-to
+
+- Open the `ogstools`-project in VSCode
+- Click the blue button in the left-bottom corner
+- Click on `Reopen in Container`
+
+Now you are inside the container. You can e.g. open a new terminal (`Terminal` / `New Terminal`) and then run some tests with `pytest` or use the [`Testing`-sidebar](https://code.visualstudio.com/docs/python/testing#_run-tests) to select specific tests to debug.
+
+## Container specification
+
+[`.devcontainer/devcontainer.json`](https://gitlab.opengeosys.org/ogs/tools/ogstools/-/tree/main/.devcontainer/devcontainer.json) (see also [available settings](https://containers.dev)):
+
+:::{literalinclude} ../../.devcontainer/devcontainer.json
+:language: json
+:::
+
+[`.devcontainer/Dockerfile`](https://gitlab.opengeosys.org/ogs/tools/ogstools/-/tree/main/.devcontainer/Dockerfile):
+
+:::{literalinclude} ../../.devcontainer/Dockerfile
+:language: Dockerfile
+:::
+
+# Container usage without VSCode
+
+:::{admonition} Advanced topic
+:class: caution
+
+If you know some Docker the container can also manually run with e.g.:
+
+```bash
+docker run --rm -it -v $PWD:$PWD -w $PWD registry.opengeosys.org/ogs/tools/ogstools/devcontainer-3.9 /bin/bash
+# Inside the container:
+make setup_devcontainer
+pytest
+```
+
+Please also be aware of permission issue when mounting your working directory.
+
+:::
--
GitLab