Add note about workspaces. (#692)

Author: tobiasraabe

docs/source/how_to_guides/bp_structure_of_a_research_project.md

@@ -23,6 +23,10 @@ As an example, look at two repositories from a COVID-19 forecasting project.
 - [sid](https://github.com/covid-19-impact-lab/sid) contains the code for the
   epidemiological model which is applied in the research project.
 
+```{seealso}
+Nowadays, consider using [workspaces](using_workspaces.md) instead of separate repositories.
+```
+
 Separating the model code from the research project provided several benefits.
 
 - The model code is isolated and has its own test suite. Assessing and ensuring the code

docs/source/how_to_guides/index.md

@@ -23,6 +23,7 @@ provisional_nodes_and_task_generators
 writing_custom_nodes
 extending_pytask
 the_data_catalog
+using_workspaces
 ```
 
 ## Best Practice Guides

docs/source/how_to_guides/using_workspaces.md

@@ -0,0 +1,51 @@
+# Using workspaces
+
+There are situations where you want to structure your project as a multi-package
+workspace. Reasons are
+
+- You are developing a scientific package alongside the project that you want to publish
+  later.
+- The code for dealing with the dataset should be reused in other projects.
+- You want to strictly separate the pytask tasks from the remaining code to be able to
+  switch to another build system.
+
+In those instances, a workspace might be the right choice.
+
+```text
+project
+├── packages
+│   ├── data
+│   │   ├── pyproject.toml
+│   │   └── src
+│   │       └── data
+│   │           ├── __init__.py
+│   │           └── ...
+│   ├── analysis
+│   │   ├── pyproject.toml
+│   │   └── src
+│   │       └── analysis
+│   │           ├── __init__.py
+│   │           └── ...
+│   └── tasks
+│       ├── pyproject.toml
+│       └── src
+│           └── tasks
+│               ├── __init__.py
+│               └── ...
+│
+├── pyproject.toml
+├── README.md
+├── ...
+```
+
+## Using workspaces with uv
+
+uv provides excellent support for workspaces which you can read more about in the
+[uv documentation](https://docs.astral.sh/uv/concepts/projects/workspaces).
+
+## Using workspaces with pixi
+
+pixi is still working on a native workspace experience, but there are workarounds.
+
+- [https://github.com/prefix-dev/pixi/discussions/387](https://github.com/prefix-dev/pixi/discussions/387)
+- [https://github.com/Andre-Medina/python-pixi-mono-template](https://github.com/Andre-Medina/python-pixi-mono-template)

docs/source/tutorials/set_up_a_project.md

@@ -6,6 +6,12 @@ tutorial explains the minimal setup.
 If you want to use pytask with a collection of scripts, you can skip this lesson and
 move to the next section of the tutorials.
 
+```{seealso}
+In case you are thinking about developing multiple packages in the project that should be separated (one for dealing with the data, one for the analysis and a package for the pytask tasks), consider using a [workspace](../how_to_guides/using_workspaces.md).
+```
+
+## The directory structure
+
 The following directory tree gives an overview of the project's different parts.
 
 ```text
@@ -83,6 +89,10 @@ version = "0.1.0"
 requires-python = ">=3.9"
 dependencies = ["pytask"]
 
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
 [tool.pytask.ini_options]
 paths = ["src/my_project"]
 ```
@@ -104,6 +114,10 @@ requires-python = ">=3.9"
 channels = ["conda-forge"]
 platforms = ["linux-64", "osx-64", "osx-arm64", "win-64"]
 
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
 [dependencies]
 pytask = "*"
 python = ">=3.9"
@@ -120,16 +134,16 @@ paths = ["src/my_project"]
 Create a `pyproject.toml` file for project configuration:
 
 ```toml
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
 [project]
 name = "my_project"
 version = "0.1.0"
 requires-python = ">=3.9"
 dependencies = ["pytask"]
 
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
 [tool.pytask.ini_options]
 paths = ["src/my_project"]
 ```
@@ -162,15 +176,15 @@ dependencies:
 And a `pyproject.toml` file for project configuration:
 
 ```toml
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
 [project]
 name = "my_project"
 version = "0.1.0"
 requires-python = ">=3.9"
 
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling"
+
 [tool.pytask.ini_options]
 paths = ["src/my_project"]
 ```