Merge pull request #16 from gkaf89/feature/micromamba

Use Conda with other package and environment management tools

docs/environment/conda.md

@@ -145,3 +145,85 @@ micromamba deactivate
 _Useful scripting resources_
 
 - [Formatting submission scripts for R (and other systems)](../slurm/launchers.md#serial-task-script-launcher)
+
+## Combining Conda with package and environment management tools
+
+Quite often it may be desirable to use Conda to manage environments but a different tool to manage packages. For instance we may want to install some packages that are not available in a Conda channel with Pip. We may also want to manage sub-environments with a different tool. For instance we may want to setup some project in a directory with Pipenv. Conda integrates well with any such tool given that each package is managed by a unique tool. Some of the most frequent cases are described bellow.
+
+### Managing packages with different tools
+
+#### Pip
+
+Many less popular Python packages are available through Pip but they are not found in any Conda channel. For instance, to manage an environment with `mkdocs` packages from Pip, create and environment
+```bash
+micromamba env create --name mkdocs
+```
+activate the environment,
+```bash
+micromamba activate mkdocs
+```
+and install `pip`:
+```bash
+micromamba install --channel conda-forge pip
+```
+
+The `pip` will be the only package that will be managed with Conda. For instance, to update Pip activate the environment,
+```bash
+micromamba activate mkdocs
+```
+and run:
+```bash
+micromaba update --all
+```
+All other packages are now managed by `pip`.
+
+For instance, assume that a `mkdocs` project requires the following packages:
+- `mkdocs`
+- `mkdocs-minify-plugin`
+The package `mkdocs-minify-plugin` is not available in Conda, but is available with Pip. To install it, activate the `mkdocs` environment
+```bash
+micromamba activate mkdocs
+```
+and install the required packages with `pip`:
+```bash
+pip install mkdocs mkdocs-minify-plugin
+```
+The packages will be installed inside the micromamba directory, for instance
+```
+${HOME}/micromamba/envs/mkdocs
+```
+and will not interfere with system packages.
+
+!!! important ""
+    **Do not install packages with pip as a user:** User packages are installed in the same directory for all environments, and can interfere with other versions of the same package.
+
+### Combining Conda with other environment and package management tools
+
+Quite often the user may want to create subenvironments, for instance tools such as `pipenv` and `poetry` manage environment and packages as project files, which an be stored in a project directory and version controlled as part of a project. Using such tools with Conda is relatively straight forward. Create an environment where only the tool that you require is installed, and manage the project subenvironments using the installed tool.
+
+!!! important ""
+    **Create a different environment for each tool:** While this is not a requirement it is a good practice. For instance, `pipenv` and `poetry` used to and may still have conflicting dependencies.
+
+#### Pipenv
+
+To demonstrate the usage of `pipenv`, create a Conda environment,
+```bash
+micromamba enc create --name pipenv
+```
+activate it
+```bash
+micromamba activate pipenv
+```
+and install the `pipenv` package as the only package in this environment:
+```bash
+micromamba install --channel conda-forge pipenv
+```
+Now the `pipenv` is managed with Conda, for instance to update `pipenv` activate the environment
+```bash
+micromamba activate pipenv
+```
+and call:
+```bash
+micromamba update --all
+```
+Inside the environment use `pipenv` as usual to create and manage project environments.