Fix CI yaml. Add notes on Python env.

.gitlab-ci.yml

@@ -17,7 +17,7 @@ build-user-manual:
 
 pages:
   image: alpine:latest
-  stage: deploy
+  stage: "Deploy"
   script:
     - mv user_manual/_sphinx_build/html public  # folder has to be named "public" for gitlab to publish it
   artifacts:

cmake/PrepareSFG.cmake

@@ -36,8 +36,6 @@ if( WALBERLA_CODEGEN_USE_PRIVATE_VENV )
         set( _wlb_codegen_python_init ${_venv_python_exe} )
         mark_as_advanced(_sfg_private_venv_done)
     endif()
-
-    set(PystencilsSfg_PYTHON_PATH ${_venv_python_exe})
 else()
     #   Use the external Python environment, but check if all packages are installed
     find_package( Python COMPONENTS Interpreter REQUIRED )
@@ -58,6 +56,7 @@ else()
     set( _wlb_codegen_python_init ${Python_EXECUTABLE} )
 endif()
 
+set(PystencilsSfg_PYTHON_PATH ${_wlb_codegen_python_init})
 set(
     WALBERLA_CODEGEN_PYTHON
     ${_wlb_codegen_python_init}

user_manual/index.md

@@ -32,6 +32,13 @@ GeneratorScriptBasics/GeneratorScriptBasics
 ForceDrivenChannel/ForceDrivenChannel
 :::
 
+:::{toctree}
+:caption: Reference
+:maxdepth: 1
+
+Python Environment <reference/PythonEnvironment>
+:::
+
 
 [pystencils_2_0]: https://da15siwa.pages.i10git.cs.fau.de/dev-docs/pystencils-nbackend/ "pystencils 2.0 Documentation"
 [pystencils-sfg]: https://pycodegen.pages.i10git.cs.fau.de/pystencils-sfg/index.html "pystencils-sfg Documentation"

user_manual/reference/PythonEnvironment.md

+# Managing the Code Generator's Python Environment
+
+On this page, you can find information on managing, customizing, and extending the Python environment
+used by the waLBerla code generation system.
+
+## Using the Default Virtual Environment
+
+By default, `sfg-walberla` creates a new Python virtual environment within the CMake build tree,
+and there installs all packages required for code generation.
+
+### Install Additional Packages
+
+For projects that require external dependencies, *sfg-walberla* exposes the CMake function
+`walberla_codegen_venv_install`, which can be used to install additional packages into the
+code generator virtual environment;
+for instance, the following invocation installs `pyyaml`:
+
+```CMake
+walberla_codegen_venv_install( pyyaml )
+```
+
+The arguments passed to `walberla_codegen_venv_install` are forwarded directly to `pip install`.
+You can therefore use any parameters that `pip` can interpret, for instance `-e` to perform an
+editable install, or `-r <requirements-file>` to install packages from a requirements file.
+
+## Using an External Virtual Environment
+
+To have even more control over your Python environment, you can configure sfg-walberla to
+forego creating a private virtual environment, and instead use the Python interpreter
+supplied from the outside.
+
+To explicitly specify a Python interpreter, you need to set the `WALBERLA_CODEGEN_USE_PRIVATE_VENV` cache
+variable to `FALSE`, and set `Python_EXECUTABLE` to point at your Python binary.
+For instance, at configuration time:
+
+```bash
+cmake -S . -B build -DWALBERLA_CODEGEN_USE_PRIVATE_VENV=FALSE -DPython_EXECUTABLE=<path-to-python>
+```