From 20c2912d9ac288fd65b7eb66254e1dfc6fed9de8 Mon Sep 17 00:00:00 2001
From: Matthew Feickert <matthew.feickert@cern.ch>
Date: Fri, 7 Nov 2025 16:18:40 -0700
Subject: [PATCH] enh: Revise Pixi subsection in package dependency section

* Use 'Pixi' to follow the prefix.dev style.
* Clarify Pixi is an environment management tool that is able to treat
  conda packages and Python packages with parity, but that it defaults
  to conda packages.
   - Add links to Pixi documentation.
   - Add note that conda environment definition files can be 'imported'
     to initialize Pixi workspaces.
* Clarify distinction of conda packages, as 'conda' as term is overloaded.
* In note to conda users, make installation with '--no-deps' its own code block
  to highlight behaviors recommended to users and make them easily copyable.
* Remove duplicated section.
* Remove 'todo' item requesting review.
---
 .../declare-dependencies.md                   | 77 +++++++------------
 1 file changed, 26 insertions(+), 51 deletions(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index 2d43c792..f8aebb55 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -406,10 +406,8 @@ dependencies = [
 
 
 :::{todo}
-### Using conda and pixi
+### Using conda and Pixi
 
-::::{todo}
-Ask Matthew to review this section...
 :::
 
 The `pyproject.toml` file works great for pure-Python packages. However,
@@ -423,64 +421,41 @@ You can maintain an `environment.yml` file to help users and contributors
 set up conda environments. This is especially useful for packages with
 system-level dependencies like GDAL.
 
-**Consider pixi for conda workflows:**
+**Consider Pixi for conda package focused workflows:**
+
+[Pixi](https://pixi.sh) is a modern package manager built on top of both
+the conda and Python package ecosystems.
+Pixi is able to treat conda and Python package requirements with parity when
+resolving environments, but uses a "conda-first" approach of using already
+resolved conda packages if possible when resolving Python dependencies.
+Pixi [can also use `pyproject.toml` for configuration](https://pixi.sh/latest/python/pyproject_toml/).
+If your project relies heavily on conda packages, Pixi offers a streamlined
+workflow with faster dependency resolution and automatic lock file support for
+full environment reproducibility.
+If you already have an existing conda environment definition file, like
+an `environment.yml`, you can
+[import the environment](https://pixi.sh/latest/tutorials/import/) into a new
+Pixi workspace with
 
-[Pixi](https://pixi.sh) is a modern package manager built on conda that
-uses `pyproject.toml` for configuration. If your project relies heavily
-on conda packages, pixi offers a streamlined workflow with lockfiles and
-faster dependency resolution.
+```
+pixi init --import environment.yml
+```
 
 :::{admonition} A note for conda users
 :class: tip
 
 If you use a conda environment for development and install your package
-with `python -m pip install -e .`, dependencies will be installed from
-PyPI rather than conda. This can cause conflicts, especially for packages
-with system dependencies.
+with `python -m pip install -e .` dependencies will be installed from PyPI,
+potentially overwriting conda packages that had already been installed.
+This can cause conflicts, especially for packages with system dependencies.
 
 To avoid this, install your package without dependencies:
-`python -m pip install -e . --no-deps`
-
-Then install dependencies through your conda environment.yml file.
-:::
-::::
-
-### Using conda and pixi
-
-:::{todo}
-Ask matthew to review this section...
-:::
-
-The `pyproject.toml` file works great for pure-Python packages. However,
-some packages (particularly in the scientific Python ecosystem) require
-dependencies written in other languages like C or Fortran. Conda was
-created to support the distribution of tools with non-Python dependencies.
-
-**For conda users:**
-
-You can maintain an `environment.yml` file to help users and contributors
-set up conda environments. This is especially useful for packages with
-system-level dependencies like GDAL.
-
-**Consider pixi for conda workflows:**
 
-[Pixi](https://pixi.sh) is a modern package manager built on conda that
-uses `pyproject.toml` for configuration. If your project relies heavily
-on conda packages, pixi offers a streamlined workflow with lockfiles and
-faster dependency resolution.
-
-:::{admonition} A note for conda users
-:class: tip
-
-If you use a conda environment for development and install your package
-with `python -m pip install -e .`, dependencies will be installed from
-PyPI rather than conda. This can cause conflicts, especially for packages
-with system dependencies.
-
-To avoid this, install your package without dependencies:
-`python -m pip install -e . --no-deps`
+```
+python -m pip install -e . --no-deps
+```
 
-Then install dependencies through your conda environment.yml file.
+Then install dependencies through your conda `environment.yml` file.
 :::
 
 ## Dependencies in Read the Docs