Merge branch 'topic/default/doc' into 'branch/default'

doc install-locked-env and co

See merge request fluiddyn/fluidsim!448

Author: paugier

README.md

@@ -32,6 +32,12 @@ pip install fluidsim
 There are also conda packages in the conda-forge channel usable with
 [Pixi](https://pixi.sh) or [conda/mamba](https://github.com/conda-forge/miniforge).
 
+The simplest way to get a production environment using the conda-forge packages is with
+
+```sh
+uvx install-locked-env https://github.com/fluiddyn/fluidsim/tree/branch/default/pixi-envs/env-fluidsim-mpi
+```
+
 Much more detailed instructions are given in
 [the documentation](https://fluidsim.readthedocs.io/en/latest/install.html).
 

doc/build-from-source.md

@@ -41,9 +41,12 @@ Cloud](https://www.clever-cloud.com) for providing <https://foss.heptapod.net>!
 
 ## Installing from the repository
 
-### Simple installation from source
+We describe few methods to install Fluidsim from source. Most developers should adopt
+[the method using PDM](#setup-dev-env).
 
-We recommend to create a clean virtual environment, for example with:
+### Simple installation from source with Pip
+
+When using Pip, we recommend to create a clean virtual environment, for example with:
 
 ```sh
 cd fluidsim
@@ -172,19 +175,21 @@ Note that Fluidsim builds are not sensible to the [`~/.pythranrc` file](pythranr
 
 ```
 
+(setup-dev-env)=
+
 ### Setup a full developer environment with editable installation
 
 Let us first present the tools used for Fluidsim development.
 
-- [PDM] is a modern Python package and dependency manager,
+- [Pip] is the official package installer for Python,
 
-- [Meson] is an open source build system (in particular used by Scipy),
+- [PDM] is a modern Python package and dependency manager,
 
 - [Nox] is a command-line tool that automates testing in multiple Python environments,
 
-- [Pytest] is the most popular testing framework for Python,
+- [Meson] is an open source build system (in particular used by Scipy),
 
-- [pip] is the official package installer for Python,
+- [Pytest] is the most popular testing framework for Python,
 
 - [Pythran] is an ahead of time compiler for a subset of the Python language, with a
   focus on scientific computing,
@@ -196,6 +201,11 @@ Fluidsim is built with [Meson]. We use [PDM] for Fluidsim development. [Pytest]
 are used for testing. We use [Pythran] through [Transonic] to accelerate some numerical
 kernels written in Python.
 
+```{note}
+Most dependencies (Meson, Pytest, Pythran, Transonic, ...) will be installed by PDM.
+The developers just have to install manually PDM (and potentially Nox).
+```
+
 #### Standard Python from Python.org
 
 We present here how one can build Fluidsim from source like the main developers and
@@ -214,15 +224,33 @@ pipx install pdm -U
 
 Installing in editable mode is a bit particular with Meson, since editable installations
 are incompatible with isolated builds, meaning that all build dependencies have to be
-installed in the main virtual environment! Fortunatelly, it's not too difficult with
-[PDM]. From the root directory of the repository, just run:
+installed in the main virtual environment! Fortunatelly, it's simple with [PDM].
+
+##### Build-install Fluidimage with PDM
+
+```{warning}
+You should not run the following commands from a virtual environment not related to Fluidimage.
+
+No need to manually create a dedicated environment since PDM is going to do it for you.
+Just deactivate all Python environments.
+```
+
+From the root directory of the repository, just run:
+
+```sh
+pdm sync --clean -v
+```
+
+This command creates a virtual environment, installs all build and runtime dependencies,
+and finally build/install Fluidsim from source.
+
+Alternativelly, one can split this process in two steps. First, install all dependencies:
 
 ```sh
-pdm install --no-self
+pdm sync --no-self --clean
 ```
 
-This command creates a virtual environment and installs all build and runtime
-dependencies. You can then activate this environment and build/install Fluidsim with:
+You can then activate the environment and build/install Fluidsim with:
 
 ```sh
 . .venv/bin/activate

doc/install.md

@@ -100,10 +100,22 @@ environments in the Fluidsim repository
 - `env-fluidsim-mpi` is for running sequential and parallel (MPI) simulations and
   post-process results. It is only available on Linux.
 
-First, get one of these directories locally on your computer (the easiest is to clone the
-Mercurial repo <https://foss.heptapod.net/fluiddyn/fluidsim> or the Git mirror
-<https://github.com/fluiddyn/fluidsim/>). To install and to use one of these
-environments, enter into the directory and run `pixi shell`.
+The simplest solution to install one of these environment locally is to use `uv` and the
+tool `install-locked-env` like this:
+
+```sh
+cd where/you/want/to/have/the/pixi/env/directory
+uvx install-locked-env https://github.com/fluiddyn/fluidsim/tree/branch/default/pixi-envs/env-fluidsim
+```
+
+To use one of these environments, enter into the directory and run `pixi shell`.
+
+```{admonition} Alternative method without install-locked-env
+Alternatively, one needs to get these directories locally on your computer
+(for example by cloning the Mercurial repo
+<https://foss.heptapod.net/fluiddyn/fluidsim> or the Git mirror
+<https://github.com/fluiddyn/fluidsim/>) and run `pixi shell`.
+```
 
 ````{admonition} How to activate such environment in shell scripts?
 
@@ -115,6 +127,8 @@ eval "$(pixi shell-hook --manifest-path ~/dev/fluidsim/pixi-envs/env-fluidsim-mp
 
 ````{admonition} How to register a Jupyter kernel using this environment
 
+(This step should already have been done if you used `install-locked-env`.)
+
 ```sh
 pixi shell --manifest-path ~/dev/fluidsim/pixi-envs/env-fluidsim-mpi
 python -m ipykernel install --user --name=env-fluidsim-mpi

doc/related-projects.md

@@ -1,6 +1,7 @@
 # Related projects
 
-There are many CFD framework and Fourier pseudo-spectral solvers. We just list here few examples:
+There are many CFD framework and Fourier pseudo-spectral solvers. We just list here few
+examples:
 
 ## Open-source
 
@@ -20,4 +21,5 @@ There are many CFD framework and Fourier pseudo-spectral solvers. We just list h
 
 ## Not open-source
 
-- [GESTS](https://impact.ornl.gov/en/publications/gpu-enabled-extreme-scale-turbulence-simulations-fourier-pseudo-s/) (P.K. Yeung)
+- [GESTS](https://impact.ornl.gov/en/publications/gpu-enabled-extreme-scale-turbulence-simulations-fourier-pseudo-s/)
+  (P.K. Yeung)