docs: add transitioning docs for poetry and conda
#1624
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Hofer-Julian
approved these changes
Jul 17, 2024
docs/switching_from/poetry.md
Outdated
| | 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 of the package. | | ||
| | Uninstalling a Package | `poetry remove numpy` | `pixi remove numpy` | |
There was a problem hiding this comment.
Is there a PyPI version for pixi remove? If yes, maybe mention it as well.
There was a problem hiding this comment.
Yep added it, thanks.
docs/switching_from/poetry.md
Outdated
| Make sure that `python` is only defined in the `tool.pixi.dependencies` and not in the `tool.pixi.pypi-dependencies`. | ||
|
|
||
| !!! Danger | ||
| It's possible to use `poetry` in `pixi` environments but this is advised against. |
There was a problem hiding this comment.
Maybe specify the risk. Is it only more maintenance, or is there more to it?
There was a problem hiding this comment.
Tried to add more information.
ruben-arts
changed the title
poetry and conda
Co-authored-by: Hofer-Julian <30049909+Hofer-Julian@users.noreply.github.com>
Co-authored-by: Hofer-Julian <30049909+Hofer-Julian@users.noreply.github.com>
Co-authored-by: Hofer-Julian <30049909+Hofer-Julian@users.noreply.github.com>
Co-authored-by: Hofer-Julian <30049909+Hofer-Julian@users.noreply.github.com>
abkfenris
reviewed
Jul 17, 2024
|
|
||
| ## Why Pixi? | ||
|
|
||
| `Pixi` builds upon the foundation of the conda ecosystem, introducing a project-centric approach rather than focusing solely on environments. |
There was a problem hiding this comment.
Suggested change
| `Pixi` builds upon the foundation of the conda ecosystem, introducing a project-centric approach rather than focusing solely on environments. | |
| `Pixi` builds upon the foundation of the conda ecosystem, introducing a project-centric approach rather than focusing solely on named global environments. |
| ## 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. |
There was a problem hiding this comment.
Maybe specify that the dependency management is automated rather than manual?
Suggested change
| This shift towards projects offers a more organized and efficient way to manage dependencies and run code, tailored to modern development practices. | |
| This shift towards projects offers a more automated, organized, and efficient way to manage dependencies and run code, tailored to modern development practices. |
| !!! 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. |
There was a problem hiding this comment.
Suggested change
| Using `pixi global install bat` will install `bat` in a global environment, which is not the same as the `base` environment in conda. | |
| Using `pixi global install bat` will install `bat` in an isolated global environment (similar to pipx), which is not the same as the `base` environment in conda. |
Comment on lines
+28
to
+32
| ??? 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)" |
There was a problem hiding this comment.
I'd emphasize pixi shell, possibly with it's own section over using shell-hook.
It would also be worth showing how --manifest-path can be used to point to activate a shell from a different directory.
| 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)) |
There was a problem hiding this comment.
Maybe a callout on how Pixi can lock for multiple platforms to help enable collaboration to highlight Pixi's additional abilities?
| Using that `pip` binary will install packages in the `pip` environment, making it unreachable form anywhere as you can't activate it. | ||
|
|
||
|
|
||
| ## Automated switching |
There was a problem hiding this comment.
Automated switching feels like it describes Pixi using the right task environment over moving from environment.yml.
Suggested change
| ## Automated switching | |
| ## Migrating from environment.yml |
Comment on lines
+44
to
+50
| 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. |
There was a problem hiding this comment.
I might move this to troubleshooting, as having it here makes it sound more like a suggestion on the best way for a Conda user to use Pixi.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is a starting point to start adding more beginner friendly documentation.
Disclaimer, I've not used
condamambapoetrymore then just for examples. The deeper details are not known to me. So any improvements are welcome, that said this should merge fast and incrementally improve overtime.