From af72faf5b9b10adeea95b96572b461ba749ba5af Mon Sep 17 00:00:00 2001
From: Olivier Lacroix <olivier.lacroix@m4x.org>
Date: Tue, 7 May 2024 21:00:38 +1000
Subject: [PATCH] Document the add & remove cli behaviour with pyproject.toml
 manifest

---
 docs/reference/cli.md | 10 ++++++++++
 src/cli/add.rs        | 10 ++++++++--
 src/cli/remove.rs     |  5 +++++
 3 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index ae54923df..2dc479f66 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -53,6 +53,12 @@ Adds dependencies to the [manifest file](configuration.md).
 It will only add if the package with its version constraint is able to work with rest of the dependencies in the project.
 [More info](../features/multi_platform_configuration.md) on multi-platform configuration.
 
+If the project manifest is a `pyproject.toml`, adding a pypi dependency will add it to the native pyproject `project.dependencies` array, or to the native `project.optional-dependencies` table if a feature is specified:
+- `pixi add --pypi boto3` would add `boto3` to the `project.dependencies` array
+- `pixi add --pypi boto3 --feature aws` would add `boto3` to the `project.dependencies.aws` array
+
+These dependencies will be read by pixi as if they had been added to the pixi `pypi-dependencies` tables of the default or a named feature.
+
 ##### Arguments
 
 1. `<SPECS>`: The package(s) to add, space separated. The version constraint is optional.
@@ -181,6 +187,10 @@ pixi run --environment cuda python
 
 Removes dependencies from the [manifest file](configuration.md).
 
+If the project manifest is a `pyproject.toml`, removing a pypi dependency with the `--pypi` flag will remove it from either
+- the native pyproject `project.dependencies` array or the native `project.optional-dependencies` table (if a feature is specified)
+- pixi `pypi-dependencies` tables of the default or a named feature (if a feature is specified)
+
 ##### Arguments
 
 1. `<DEPS>...`: List of dependencies you wish to remove from the project.
diff --git a/src/cli/add.rs b/src/cli/add.rs
index 99a871e73..7a58bd0ef 100644
--- a/src/cli/add.rs
+++ b/src/cli/add.rs
@@ -52,10 +52,16 @@ pub struct Args {
     ///
     /// Mixing `--platform` and `--build`/`--host` flags is supported
     ///
-    /// The `--pypi` option will add the package as a pypi-dependency this can not be mixed with the conda dependencies
+    /// The `--pypi` option will add the package as a pypi dependency. This can not be mixed with the conda dependencies
     /// - `pixi add --pypi boto3`
     /// - `pixi add --pypi "boto3==version"
     ///
+    /// If the project manifest is a `pyproject.toml`, adding a pypi dependency will add it to the native pyproject `project.dependencies` array
+    /// or to the native `project.optional-dependencies` table if a feature is specified:
+    /// - `pixi add --pypi boto3` would add `boto3` to the `project.dependencies` array
+    /// - `pixi add --pypi boto3 --feature aws` would add `boto3` to the `project.dependencies.aws` array
+    /// These dependencies will be read by pixi as if they had been added to the pixi `pypi-dependencies` tables of the default or a named feature.
+    ///
     #[arg(required = true)]
     pub specs: Vec<String>,
 
@@ -87,7 +93,7 @@ pub struct Args {
     #[arg(long, short)]
     pub platform: Vec<Platform>,
 
-    /// The feature for which the dependency should be added
+    /// The feature for which the dependency should be added.
     #[arg(long, short)]
     pub feature: Option<String>,
 
diff --git a/src/cli/remove.rs b/src/cli/remove.rs
index 8c4d87d07..88ef59334 100644
--- a/src/cli/remove.rs
+++ b/src/cli/remove.rs
@@ -14,6 +14,11 @@ use crate::project::manifest::FeatureName;
 use crate::{consts, project::SpecType, Project};
 
 /// Remove the dependency from the project
+///
+/// If the project manifest is a `pyproject.toml`, removing a pypi dependency with the `--pypi` flag will remove it from either
+/// - the native pyproject `project.dependencies` array or the native `project.optional-dependencies` table (if a feature is specified)
+/// - pixi `pypi-dependencies` tables of the default or a named feature (if a feature is specified)
+///
 #[derive(Debug, Default, Parser)]
 pub struct Args {
     /// List of dependencies you wish to remove from the project