From 44403b2b1e15593cabfb9f715d436cb6a4751cc4 Mon Sep 17 00:00:00 2001
From: Randy Syring <randy@syrings.us>
Date: Fri, 21 Feb 2025 01:15:06 -0500
Subject: [PATCH] docs: refactor/enhance group dependencies

- Add example of dependency group includes
- Refactor section to to show pyproject.toml config & explanation of dependency resolution first and move CLI implementation and options into it's own section
---
 docs/concepts/projects/dependencies.md | 92 ++++++++++++++++----------
 1 file changed, 57 insertions(+), 35 deletions(-)

diff --git a/docs/concepts/projects/dependencies.md b/docs/concepts/projects/dependencies.md
index 5624c3ca690a..267e68537bd4 100644
--- a/docs/concepts/projects/dependencies.md
+++ b/docs/concepts/projects/dependencies.md
@@ -585,20 +585,23 @@ url = "https://download.pytorch.org/whl/cu124"
 
 ## Development dependencies
 
+uv uses the `[dependency-groups]` table (as defined in [PEP 735](https://peps.python.org/pep-0735/))
+for declaration of development dependencies.
+
 Unlike optional dependencies, development dependencies are local-only and will _not_ be included in
 the project requirements when published to PyPI or other indexes. As such, development dependencies
 are not included in the `[project]` table.
 
-Development dependencies can have entries in `tool.uv.sources` the same as normal dependencies.
+### "Dev" group
 
-To add a development dependency, use the `--dev` flag:
+uv has special handling for the "dev" dependency group. To add a development dependency, use the
+`--dev` flag:
 
 ```console
 $ uv add --dev pytest
 ```
 
-uv uses the `[dependency-groups]` table (as defined in [PEP 735](https://peps.python.org/pep-0735/))
-for declaration of development dependencies. The above command will create a `dev` group:
+which creates a `dev` group in the project's config:
 
 ```toml title="pyproject.toml"
 [dependency-groups]
@@ -607,65 +610,84 @@ dev = [
 ]
 ```
 
-The `dev` group is special-cased; there are `--dev`, `--only-dev`, and `--no-dev` flags to toggle
-inclusion or exclusion of its dependencies. See `--no-default-groups` to disable all default groups
-instead. Additionally, the `dev` group is [synced by default](#default-groups).
+### Default group(s)
 
-### Dependency groups
+By default, uv includes the `dev` dependency group in the environment, e.g. during `uv run` or
+`uv sync`.
 
-Development dependencies can be divided into multiple groups, using the `--group` flag.
+The default groups to include can be changed using the `tool.uv.default-groups` setting:
 
-For example, to add a development dependency in the `lint` group:
-
-```console
-$ uv add --group lint ruff
+```toml title="pyproject.toml"
+[tool.uv]
+default-groups = ["dev", "foo"]
 ```
 
-Which results in the following `[dependency-groups]` definition:
+!!! tip
+
+    To disable this behaviour during `uv run` or `uv sync`, use `--no-default-groups`.
+
+### Additional groups
+
+Support for dependency groups extends beyond the `dev` group:
 
 ```toml title="pyproject.toml"
 [dependency-groups]
 dev = [
-  "pytest"
+  {include-group = "lint"},
+  "pytest",
 ]
 lint = [
   "ruff"
 ]
 ```
 
-Once groups are defined, the `--all-groups`, `--no-default-groups`, `--group`, `--only-group`, and
-`--no-group` options can be used to include or exclude their dependencies.
-
-!!! tip
-
-    The `--dev`, `--only-dev`, and `--no-dev` flags are equivalent to `--group dev`,
-    `--only-group dev`, and `--no-group dev` respectively.
-
 uv requires that all dependency groups are compatible with each other and resolves all groups
 together when creating the lockfile.
 
 If dependencies declared in one group are not compatible with those in another group, uv will fail
-to resolve the requirements of the project with an error.
+to resolve the requirements of the project with an error unless you explicitly
+[declare them as conflicting](./config.md#conflicting-dependencies).
 
-!!! note
+### CLI Options
 
-    If you have dependency groups that conflict with one another, resolution will fail
-    unless you explicitly [declare them as conflicting](./config.md#conflicting-dependencies).
+Development dependencies added from the CLI can be directed to a particular group using the
+`--group` flag:
 
-### Default groups
+```console
+$ uv add --group ci tox pip-audit
+```
 
-By default, uv includes the `dev` dependency group in the environment (e.g., during `uv run` or
-`uv sync`). The default groups to include can be changed using the `tool.uv.default-groups` setting.
+Which results in:
 
 ```toml title="pyproject.toml"
-[tool.uv]
-default-groups = ["dev", "foo"]
+[dependency-groups]
+ci = [
+  "pip-audit",
+  "tox",
+]
+dev = [
+  # NOTE: include-group is set by editing the file, not with `uv add` (see #9054)
+  {include-group = "lint"},
+  "pytest",
+]
+lint = [
+  "ruff"
+]
 ```
 
-!!! tip
+The CLI has multiple dependency group related options including:
 
-    To disable this behaviour during `uv run` or `uv sync`, use `--no-default-groups`.
-    To exclude a specific default group, use `--no-group <name>`.
+- `--group <group>`
+- `--only-group <group>`
+- `--no-group <group>`
+- `--dev`, `--only-dev`, and `--no-dev` which are aliases for the `dev` group and the above commands
+- `--all-groups`
+- `--no-default-groups`
+
+See [`uv run --help`][uv-run] or [`uv sync --help`][uv-sync] for an explanation of the options.
+
+[uv-run]: https://docs.astral.sh/uv/reference/cli/#uv-run
+[uv-sync]: https://docs.astral.sh/uv/reference/cli/#uv-sync
 
 ### Legacy `dev-dependencies`