docs: add transitioning docs for poetry and conda

docs/switching_from/conda.md

@@ -0,0 +1,82 @@
+# Transitioning from the `conda` or `mamba` to `pixi`
+Welcome to the guide designed to ease your transition from `conda` or `mamba` to `pixi`.
+This document compares key commands and concepts between these tools, highlighting `pixi`'s unique approach to managing environments and packages.
+With `pixi`, you'll experience a project-based workflow, enhancing your development process, and allowing for easy sharing of your work.
+
+## Why Pixi?
+
+`Pixi` builds upon the foundation of the conda ecosystem, introducing a project-centric approach rather than focusing solely on environments.
+This shift towards projects offers a more organized and efficient way to manage dependencies and run code, tailored to modern development practices.
+
+## Key Differences at a Glance
+
+| Task                        | Conda/Mamba                                       | Pixi                                                                 |
+|-----------------------------|---------------------------------------------------|----------------------------------------------------------------------|
+| Installation                | Requires an installer                             | Download and add to path (See [installation](../index.md))           |
+| Creating an Environment     | `conda create -n myenv -c conda-forge python=3.8` | `pixi init myenv` followed by `pixi add python=3.8`                  |
+| Activating an Environment   | `conda activate myenv`                            | `pixi shell` within the project directory                            |
+| Deactivating an Environment | `conda deactivate`                                | `exit` from the `pixi shell`                                         |
+| Running a Task              | `conda run -n myenv python my_program.py`         | `pixi run python my_program.py` (See [run](../reference/cli.md#run)) |
+| Installing a Package        | `conda install numpy`                             | `pixi add numpy`                                                     |
+| Uninstalling a Package      | `conda remove numpy`                              | `pixi remove numpy`                                                  |
+
+!!! warn "No `base` environment"
+    Conda has a base environment, which is the default environment when you start a new shell.
+    **Pixi does not have a base environment**. And requires you to install the tools you need in the project or globally.
+    Using `pixi global install bat` will install `bat` in a global environment, which is not the same as the `base` environment in conda.
+
+??? tip "Activating pixi environment in the current shell"
+    For some advanced use-cases, you can activate the environment in the current shell.
+    This uses the `pixi shell-hook` which prints the activation script, which can be used to activate the environment in the current shell without `pixi` itself.
+    ```shell
+    ~/myenv > eval "$(pixi shell-hook)"
+    ```
+
+## Environment vs Project
+`Conda` and `mamba` focus on managing environments, while `pixi` emphasizes projects.
+In `pixi`, a project is a folder containing a [manifest](../reference/project_configuration.md)(`pixi.toml`/`pyproject.toml`) file that describes the project, a `pixi.lock` lock-file that describes the exact dependencies, and a `.pixi` folder that contains the environment.
+
+This project-centric approach allows for easy sharing and collaboration, as the project folder contains all the necessary information to recreate the environment.
+It manages more than one environment for more than one platform in a single project, and allows for easy switching between them. (See [multiple environments](../features/multi_environment.md))
+
+## Global environments
+`conda` installs all environments in one global location.
+When this is important to you for filesystem reasons, you can use the [detached-environments](../reference/pixi_configuration.md#detached-environments) feature of pixi.
+```shell
+pixi config set detached-environments true
+# or a specific location
+pixi config set detached-environments /path/to/envs
+```
+This doesn't allow you to activate the environments using `pixi shell -n` but it will make the installation of the environments go to the same folder.
+
+`pixi` does have the `pixi global` command to install tools on your machine. (See [global](../reference/cli.md#global))
+This is not a replacement for `conda` but works the same as [`pipx`](https://pipx.pypa.io/stable/) and [`condax`](https://mariusvniekerk.github.io/condax/).
+It creates a single isolated environment for the given requirement and installs the binaries into the global path.
+```shell
+pixi global install bat
+bat pixi.toml
+```
+
+!!! warn "Never install `pip` with `pixi global`"
+Installations with `pixi global` get their own isolated environment.
+Installing `pip` with `pixi global` will create a new isolated environment with its own `pip` binary.
+Using that `pip` binary will install packages in the `pip` environment, making it unreachable form anywhere as you can't activate it.
+
+
+## Automated switching
+With `pixi` you can import `environment.yml` files into a pixi project. (See [import](../reference/cli.md#init))
+```shell
+pixi init --import environment.yml
+```
+This will create a new project with the dependencies from the `environment.yml` file.
+
+
+## Troubleshooting
+Encountering issues? Here are solutions to some common problems when being used to the `conda` workflow:
+
+- Dependency `is excluded because due to strict channel priority not using this option from: 'https://conda.anaconda.org/conda-forge/'`
+  This error occurs when the package is in multiple channels. `pixi` uses a strict channel priority. See [channel priority](../advanced/channel_priority.md) for more information.
+- `pixi global install pip`, pip doesn't work.
+  `pip` is installed in the global isolated environment. Use `pixi add pip` in a project to install `pip` in the project environment and use that project.
+- `pixi global install <Any Library>` -> `import <Any Library>` -> `ModuleNotFoundError: No module named '<Any Library>'`
+   The library is installed in the global isolated environment. Use `pixi add <Any Library>` in a project to install the library in the project environment and use that project.

docs/switching_from/poetry.md

@@ -0,0 +1,36 @@
+# Transitioning from `poetry` to `pixi`
+Welcome to the guide designed to ease your transition from `poetry` to `pixi`.
+This document compares key commands and concepts between these tools, highlighting `pixi`'s unique approach to managing environments and packages.
+With `pixi`, you'll experience a project-based workflow similar to `poetry` while including the `conda` ecosystem and allowing for easy sharing of your work.
+
+## Why Pixi?
+Poetry is most-likely the closest tool to pixi in terms of project management, in the python ecosystem.
+On top of the PyPI ecosystem, `pixi` adds the power of the conda ecosystem, allowing for a more flexible and powerful environment management.
+
+## Quick look at the differences
+| Task                       | Poetry                                                            | Pixi                                                                                                                                              |
+|----------------------------|-------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
+| Creating an Environment    | `poetry new myenv`                                                | `pixi init myenv`                                                                                                                                 |
+| Running a Task             | `poetry run which python`                                         | `pixi run which python` `pixi` uses a build-in cross platform shell for run where poetry uses your shell.                                         |
+| Installing a Package       | `poetry add numpy`                                                | `pixi add numpy` adds the conda variant. `pixi add --pypi numpy` adds the PyPI variant.                                            |
+| Uninstalling a Package     | `poetry remove numpy`                                             | `pixi remove numpy` removes the conda variant. `pixi remove --pypi numpy` removes the PyPI variant.                                               |
+| Building a package         | `poetry build`                                                    | We've yet to implement package building and publishing                                                                                            |
+| Publishing a package       | `poetry publish`                                                  | We've yet to implement package building and publishing                                                                                            |
+| Reading the pyproject.toml | `[tool.poetry]`                                                   | `[tool.pixi]`                                                                                                                                     |
+| Defining dependencies      | `[tool.poetry.dependencies]`                                      | `[tool.pixi.dependencies]` for conda, `[tool.pixi.pypi-dependencies]` or `[project.dependencies]` for PyPI dependencies                           |
+| Dependency definition      | - `numpy = "^1.2.3"`<br/>- `numpy = "~1.2.3"`<br/>- `numpy = "*"` | - `numpy = ">=1.2.3 <2.0.0"`<br/>- `numpy = ">=1.2.3 <1.3.0"`<br/>- `numpy = "*"`                                                                 |
+| Lock file                  | `poetry.lock`                                                     | `pixi.lock`                                                                                                                                       |
+| Environment directory       | `~/.cache/pypoetry/virtualenvs/myenv`                             | `./.pixi` Defaults to the project folder, move this using the [`detached-environments`](../reference/pixi_configuration.md#detached-environments) |
+
+## Support both `poetry` and `pixi` in my project
+You can allow users to use `poetry` and `pixi` in the same project, they will not touch each other's parts of the configuration or system.
+It's best to duplicate the dependencies, basically making an exact copy of the `tool.poetry.dependencies` into `tool.pixi.pypi-dependencies`.
+Make sure that `python` is only defined in the `tool.pixi.dependencies` and not in the `tool.pixi.pypi-dependencies`.
+
+!!! Danger "Mixing `pixi` and `poetry`"
+    It's possible to use `poetry` in `pixi` environments but this is advised against.
+    Pixi supports PyPI dependencies in a different way than `poetry` does, and mixing them can lead to unexpected behavior.
+    As you can only use one package manager at a time, it's best to stick to one.
+
+    If using poetry on top of a pixi project, you'll always need to install the `poetry` environment after the `pixi` environment.
+    And let `pixi` handle the `python` and `poetry` installation.

mkdocs.yml

@@ -98,6 +98,9 @@ extra:
 nav:
   - Installation: index.md
   - Basic Usage: basic_usage.md
+  - Switching from:
+      - Poetry: switching_from/poetry.md
+      - Conda/Mamba: switching_from/conda.md
   - Changelog: CHANGELOG.md
   - IDE Integration:
       - JupyterLab: ide_integration/jupyterlab.md

pixi.toml

@@ -16,7 +16,6 @@ build = "cargo build --release"
 install = "cargo install --path . --locked"
 test = "cargo test"
 test-all = "cargo test --all-features"
-lint = "pre-commit run --all"
 bump = "tbump --only-patch $RELEASE_VERSION"
 pypi-proxy = "python ./tests/pypi_proxy.py"
 
@@ -33,6 +32,7 @@ typos = ">=1.23.1,<2"
 [feature.lint.tasks]
 pre-commit-install = "pre-commit install"
 pre-commit-run = "pre-commit run --all"
+lint = { depends-on = ["pre-commit-run"] }
 
 [feature.build.dependencies]
 # Needed for building