doc: improve dependency group related documentation

python-poetry · Mar 22, 2022 · dec009d · dec009d
1 parent b3d82af
commit dec009d
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 22 deletions.
diff --git a/docs/cli.md b/docs/cli.md
@@ -215,10 +215,10 @@ option is used.
 
 ### Options
 
-* `--without`: The dependency groups to ignore for installation.
-* `--with`: The optional dependency groups to include for installation.
-* `--only`: The only dependency groups to install.
-* `--default`: Only install the default dependencies.
+* `--without`: The dependency groups to ignore.
+* `--with`: The optional dependency groups to include.
+* `--only`: The only dependency groups to include.
+* `--default`: Only include the default dependencies. (**Deprecated**)
 * `--sync`: Synchronize the environment with the locked packages and the specified groups.
 * `--no-root`: Do not install the root package (your project).
 * `--dry-run`: Output the operations but do not execute anything (implicitly enables --verbose).
@@ -227,6 +227,9 @@ option is used.
 * `--dev-only`: Only install dev dependencies. (**Deprecated**)
 * `--remove-untracked`: Remove dependencies not presented in the lock file. (**Deprecated**)
 
+{{% note %}}
+When `--only` is specified, `--with` and `--without` options are ignored.
+{{% /note %}}
 
 ## update
 
@@ -252,10 +255,18 @@ update the constraint, for example `^2.3`. You can do this using the `add` comma
 
 ### Options
 
+* `--without`: The dependency groups to ignore.
+* `--with`: The optional dependency groups to include.
+* `--only`: The only dependency groups to include.
+* `--default`: Only include the default dependencies. (**Deprecated**)
 * `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).
-* `--no-dev` : Do not install dev dependencies.
+* `--no-dev` : Do not update the development dependencies. (**Deprecated**)
 * `--lock` : Do not perform install (only update the lockfile).
 
+{{% note %}}
+When `--only` is specified, `--with` and `--without` options are ignored.
+{{% /note %}}
+
 ## add
 
 The `add` command adds required packages to your `pyproject.toml` and installs them.
@@ -425,15 +436,18 @@ required by
 
 ### Options
 
-* `--without`: Do not show the information of the specified groups' dependencies.
-* `--with`: Show the information of the specified optional groups' dependencies as well.
-* `--only`: Only show the information of dependencies belonging to the specified groups.
-* `--default`: Only show the information of the default dependencies.
-* `--no-dev`: Do not list the dev dependencies.
+* `--without`: The dependency groups to ignore.
+* `--with`: The optional dependency groups to include.
+* `--only`: The only dependency groups to include.
+* `--default`: Only include the default dependencies. (**Deprecated**)
+* `--no-dev`: Do not list the dev dependencies. (**Deprecated**)
 * `--tree`: List the dependencies as a tree.
 * `--latest (-l)`: Show the latest version.
 * `--outdated (-o)`: Show the latest version but only for packages that are outdated.
 
+{{% note %}}
+When `--only` is specified, `--with` and `--without` options are ignored.
+{{% /note %}}
 
 ## build
 

diff --git a/docs/managing-dependencies.md b/docs/managing-dependencies.md
@@ -36,6 +36,7 @@ on whether their dependencies will be resolved and installed **by default**, the
 the dependencies logically.
 {{% /note %}}
 
+{{% note %}}
 The dependencies declared in `tool.poetry.dependencies` are part of an implicit `default` group.
 
 ```toml
@@ -47,6 +48,7 @@ pendulum = "*"
 pytest = "^6.0.0"
 pytest-mock = "*"
 ```
+{{% /note %}}
 
 {{% note %}}
 **A note about the `dev-dependencies` section**
@@ -109,7 +111,14 @@ If the group does not already exist, it will be created automatically.
 
 ### Installing group dependencies
 
-**By default**, dependencies across **all groups** will be installed when executing `poetry install`.
+**By default**, dependencies across **all non-optional groups** will be installed when executing
+`poetry install`.
+
+{{% note %}}
+The default set of dependencies for a project includes the implicit `default` group defined in
+`tool.poetry.dependencies` as well as all groups that are not explicitly marked as an
+[optional group]({{< relref "#optional-groups" >}}).
+{{% /note %}}
 
 You can **exclude** one or more groups with the `--without` option:
 
@@ -123,20 +132,22 @@ You can also opt in [optional groups]({{< relref "#optional-groups" >}}) by usin
 poetry install --with docs
 ```
 
-If you only want to install the **default**, non-grouped, dependencies, you can do so
-with the `--default` option:
+Finally, in some case you might want to install **only specific groups** of dependencies
+without installing the default set of dependencies. For that purpose, you can use
+the `--only` option.
 
 ```bash
-poetry install --default
+poetry install --only docs
 ```
 
-Finally, in some case you might want to install **only specific groups** of dependencies
-without installing the default dependencies. For that purpose, you can use
-the `--only` option.
+{{% note %}}
+If you only want to install the project's runtime dependencies, you can do so  with the
+`--only default` notation:
 
 ```bash
-poetry install --only docs
+poetry install --only default
 ```
+{{% /note %}}
 
 ### Removing dependencies from a group
 

diff --git a/src/poetry/console/commands/group_command.py b/src/poetry/console/commands/group_command.py
@@ -23,27 +23,27 @@ def _group_dependency_options() -> list[Option]:
             option(
                 "without",
                 None,
-                "The dependency groups to ignore for installation.",
+                "The dependency groups to ignore.",
                 flag=False,
                 multiple=True,
             ),
             option(
                 "with",
                 None,
-                "The optional dependency groups to include for installation.",
+                "The optional dependency groups to include.",
                 flag=False,
                 multiple=True,
             ),
             option(
                 "default",
                 None,
-                "Only install the default dependencies."
+                "Only include the default dependencies."
                 " (<warning>Deprecated</warning>)",
             ),
             option(
                 "only",
                 None,
-                "The only dependency groups to install.",
+                "The only dependency groups to include.",
                 flag=False,
                 multiple=True,
             ),