Add pixi install and dev instructions to README (#77)

* Add pixi install and dev instructions to README

* Add CI test config updates

* Add manifest sharing instructions

* Remove manifest path statement in favour of note.

Author: brynpickering

README.md

@@ -29,7 +29,7 @@ This repository is maintained using [OET's soft-fork strategy](https://open-ener
 * `cutouts`: will store raw weather data cutouts from `atlite` (does not exist initially)
 * `data`: includes input data that is not produced by any `snakemake` rule
 * `doc`: includes all files necessary to build the `readthedocs` documentation of PyPSA-Eur
-* `envs`: includes all the `mamba` environment specifications to run the workflow
+* `envs`: includes backup `conda` environments if `pixi` installation does not work.
 * `logs`: will store log files (does not exist initially)
 * `notebooks`: includes all the `notebooks` used for ad-hoc analysis
 * `report`: contains all files necessary to build the report; plots and result files are generated automatically
@@ -44,25 +44,104 @@ This repository is maintained using [OET's soft-fork strategy](https://open-ener
 
 Clone the repository:
 
-    git clone https://github.com/open-energy-transition/{{repository}}
+```sh
+git clone https://github.com/open-energy-transition/{{repository}}
+```
 
-You need [mamba](https://mamba.readthedocs.io/en/latest/) to run the analysis. Users may also prefer to use [micromamba](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html) or [conda](https://docs.conda.io/projects/conda/en/latest/index.html). Using `mamba`, you can create an environment from within you can run it:
+You need [pixi](https://pixi.sh/latest/) to run the analysis.
+Once installed, activate your pixi environment in a terminal session:
 
-    mamba env create -f environment.yaml
+```sh
+pixi shell
+```
 
-Activate the newly created `{{project_short_name}}` environment:
+>[!NOTE]
+>`pixi` will create a distinct environment in every project directory, even if you have identical copies of a project cloned locally.
+>As there is a common system-level package cache, `pixi` efficiently conserves disk space in such cases.
+
+>[!TIP]
+>If `pixi` isn't working, you can install from one of the fallback `conda` environment files found in `envs`.
+>For more details see [the PyPSA-Eur installation guide](https://pypsa-eur.readthedocs.io/en/latest/installation.html).
+
+### Extra soft-fork dependencies
+
+If you add dependencies to your project, we recommend you add them to a [new `pixi` environment](https://pixi.sh/v0.21.1/features/multi_environment/#feature-environment-set-definitions).
+For instance, if you need access to `plotly`, want to pin the version of gurobi you are using, and want to add a PyPI dependency:
+
+```sh
+pixi add -f {{ project_short_name }} "gurobi<13" "plotly"
+pixi add -f {{ project_short_name }} --pypi pypsa-explorer
+```
+
+This will create these entries in your `pixi.toml`
+
+```toml
+[feature.{{ project_short_name }}.pypi-dependencies]
+pypsa-explorer = "*"
+
+[feature.{{ project_short_name }}.dependencies]
+gurobi = "<13"
+plotly = "*"
+```
+
+Then, you can create an environment from this feature in `pixi.toml`:
+
+```toml
+[environments]
+...
+{{ project_short_name }} = [{{ project_short_name }}]
+```
+
+These dependencies will be combined with the core PyPSA-Eur dependencies and can be accessed by calling:
+
+```sh
+pixi shell -e {{ project_short_name }}
+```
+
+#### Updating CI tests
+
+To run CI tests using your environment you should add the `test` feature to it and create test tasks for your environment, e.g.:
+
+```toml
+[feature.{{ project_short_name }}.tasks]
+{{ project_short_name }}-test = """
+	snakemake --configfile config/config.{{ project_short_name }}.default.yaml -n &&
+    """
+[environments]
+...
+{{ project_short_name }} = ["test", {{ project_short_name }}]
+```
+
+And then update `.github/workflows/test.yaml` to run that test:
+
+```yaml
+- name: Run project-specific snakemake test workflows
+  run: |
+    pixi run {{ project_short_name }}-test
+```
+
+If you also add your own unit tests, update the unit test runner to use your environment as well:
+
+```yaml
+- name: Run unit tests
+  run: |
+    pixi run -e {{ project_short_name }} unit-tests
+```
 
-    mamba activate {{project_short_name}}
 
 ## 2. Run the analysis
 
-    snakemake -call
+```sh
+snakemake -call
+```
 
 This will run all analysis steps to reproduce results and build the report.
 
 To generate a PDF of the dependency graph of all steps `resources/dag.pdf` run:
 
-    snakemake -c1 dag
+```sh
+snakemake -c1 dag
+```
 
 <sup>*</sup> Open Energy Transition (g)GmbH, Königsallee 52, 95448 Bayreuth, Germany