Update the documentation

docs/basic-usage.md

@@ -48,8 +48,8 @@ authors = ["Sébastien Eustace <sebastien@eustace.io>"]
 [tool.poetry.dependencies]
 python = "*"
 
-[tool.poetry.dev-dependencies]
-pytest = "^3.4"
+[tool.poetry.group.dev.dependencies]
+pytest = "^6.0"
 ```
 
 ### Initialising a pre-existing project
@@ -68,7 +68,7 @@ If you want to add dependencies to your project, you can specify them in the `to
 
 ```toml
 [tool.poetry.dependencies]
-pendulum = "^1.4"
+pendulum = "^2.1"
 ```
 
 As you can see, it takes a mapping of **package names** and **version constraints**.
@@ -82,7 +82,7 @@ Also, instead of modifying the `pyproject.toml` file by hand, you can use the `a
 $ poetry add pendulum
 ```
 
-It will automatically find a suitable version constraint **and install** the package and subdependencies.
+It will automatically find a suitable version constraint **and install** the package and sub-dependencies.
 
 
 ## Using your virtual environment
@@ -137,8 +137,8 @@ To deactivate this virtual environment simply use `deactivate`.
 
 ### Version constraints
 
-In our example, we are requesting the `pendulum` package with the version constraint `^1.4`.
-This means any version greater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`).
+In our example, we are requesting the `pendulum` package with the version constraint `^2.1`.
+This means any version greater or equal to 2.1.0 and less than 3.0.0 (`>=2.1.0 <3.0.0`).
 
 Please read [Dependency specification]({{< relref "dependency-specification" >}} "Dependency specification documentation") for more in-depth information on versions,
 how versions relate to each other, and on the different ways you can specify dependencies.
@@ -159,7 +159,7 @@ for the version constraint you have specified.
 
 ## Installing dependencies
 
-To install the defined dependencies for your project, just run the `install` command.
+To install the defined dependencies for your project, just run the [`install`]({{< relref "cli#install" >}}) command.
 
 ```bash
 poetry install
@@ -172,7 +172,7 @@ When you run this command, one of two things may happen:
 If you have never run the command before and there is also no `poetry.lock` file present,
 Poetry simply resolves all dependencies listed in your `pyproject.toml` file and downloads the latest version of their files.
 
-When Poetry has finished installing, it writes all of the packages and the exact versions of them that it downloaded to the `poetry.lock` file,
+When Poetry has finished installing, it writes all the packages and their exact versions that it downloaded to the `poetry.lock` file,
 locking the project to those specific versions.
 You should commit the `poetry.lock` file to your project repo so that all people working on the project are locked to the same versions of dependencies (more below).
 
@@ -187,7 +187,7 @@ Either way, running `install` when a `poetry.lock` file is present resolves and
 but Poetry uses the exact versions listed in `poetry.lock` to ensure that the package versions are consistent for everyone working on your project.
 As a result you will have all dependencies requested by your `pyproject.toml` file,
 but they may not all be at the very latest available versions
-(some of the dependencies listed in the `poetry.lock` file may have released newer versions since the file was created).
+(some dependencies listed in the `poetry.lock` file may have released newer versions since the file was created).
 This is by design, it ensures that your project does not break because of unexpected changes in dependencies.
 
 ### Commit your `poetry.lock` file to version control

docs/cli.md

@@ -133,20 +133,36 @@ This ensures that everyone using the library will get the same versions of the d
 
 If there is no `poetry.lock` file, Poetry will create one after dependency resolution.
 
-You can specify to the command that you do not want the development dependencies installed by passing
-the `--no-dev` option.
+If you want to exclude one or more dependency group for the installation, you can use
+the `--without` option.
 
 ```bash
-poetry install --no-dev
+poetry install --without test,docs
 ```
 
-Conversely, you can specify to the command that you only want to install the development dependencies
-by passing the `--dev-only` option. Note that `--no-dev` takes priority if both options are passed.
+{{% note %}}
+The `--no-dev` option is now deprecated. You should use the `--without dev` notation instead.
+{{% /note %}}
+
+You can also select optional dependency groups with the `--with` option.
 
 ```bash
-poetry install --dev-only
+poetry install --with test,docs
 ```
 
+It's also possible to only install specific dependency groups by using the `only` option.
+
+```bash
+poetry install --only test,docs
+```
+
+{{% note %}}
+The `--dev-only` option is now deprecated. You should use the `--only dev` notation instead.
+{{% /note %}}
+
+See [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}) for more information
+about dependency groups.
+
 If you want to remove old dependencies no longer present in the lock file, use the
 `--remove-untracked` option.
 
@@ -179,13 +195,17 @@ If you want to skip this installation, use the `--no-root` option.
 poetry install --no-root
 ```
 
-Installation of your project's package is also skipped when the `--dev-only`
-option is passed.
+Installation of your project's package is also skipped when the `--only`
+option is used.
 
 ### Options
 
-* `--no-dev`: Do not install dev dependencies.
-* `--dev-only`: Only install dev dependencies.
+* `--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.
+* `--no-dev`: Do not install dev dependencies. (**Deprecated**)
+* `--dev-only`: Only install dev dependencies. (**Deprecated**)
 * `--no-root`: Do not install the root package (your project).
 * `--dry-run`: Output the operations but do not execute anything (implicitly enables --verbose).
 * `--remove-untracked`: Remove dependencies not presented in the lock file
@@ -311,9 +331,19 @@ poetry add "requests[security,socks]~=2.22.0"
 poetry add "git+https://github.com/pallets/flask.git@1.1.1[dotenv,dev]"
 ```
 
+If you want to add a package to a specific group of dependencies, you can use the `--group (-G)` option:
+
+```bash
+poetry add mkdocs --group docs
+```
+
+See [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}) for more information
+about dependency groups.
+
 ### Options
 
-* `--dev (-D)`: Add package as development dependency.
+* `--group (-D)`: The group to add the dependency to.
+* `--dev (-D)`: Add package as development dependency. (**Deprecated**)
 * `--editable (-e)`: Add vcs/path dependencies as editable.
 * `--extras (-E)`: Extras to activate for the dependency. (multiple values allowed)
 * `--optional`: Add as an optional dependency.
@@ -334,9 +364,19 @@ list of installed packages.
 poetry remove pendulum
 ```
 
+If you want to remove a package from a specific group of dependencies, you can use the `--group (-G)` option:
+
+```bash
+poetry remove mkdocs --group docs
+```
+
+See [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}) for more information
+about dependency groups.
+
 ### Options
 
-* `--dev (-D)`: Removes a package from the development dependencies.
+* `--group (-D)`: The group to remove the dependency from.
+* `--dev (-D)`: Removes a package from the development dependencies. (**Deprecated**)
 * `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).
 
 
@@ -365,6 +405,10 @@ dependencies:
 
 ### 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.
 * `--tree`: List the dependencies as a tree.
 * `--latest (-l)`: Show the latest version.

docs/dependency-specification.md

@@ -210,21 +210,21 @@ you can shift from using "inline table" syntax, to the "standard table" syntax.
 An example where this might be useful is the following:
 
 ```toml
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.dev.dependencies]
 black = {version = "19.10b0", allow-prereleases = true, python = "^3.6", markers = "platform_python_implementation == 'CPython'"}
 ```
 
-As a single line, this is a lot to digest. To make this a little bit easier to
+As a single line, this is a lot to digest. To make this a bit easier to
 work with, you can do the following:
 
 ```toml
-[tool.poetry.dev-dependencies.black]
+[tool.poetry.group.dev.dependencies.black]
 version = "19.10b0"
 allow-prereleases = true
 python = "^3.6"
 markers = "platform_python_implementation == 'CPython'"
 ```
 
-All of the same information is still present, and ends up providing the exact
+The same information is still present, and ends up providing the exact
 same specification. It's simply split into multiple, slightly more readable,
 lines.

docs/managing-dependencies.md

@@ -0,0 +1,141 @@
+---
+draft: false
+layout: single
+menu:
+ docs:
+ weight: 11
+title: Managing dependencies
+type: docs
+---
+
+
+# Managing dependencies
+
+## Dependency groups
+
+Poetry provides a way to **organize** your dependencies by **groups**. For instance, you might have
+dependencies that are only needed to test you project or to build the documentation.
+
+To declare a new dependency group, use a `tool.poetry.group.<group>` section
+where `<group>` is the name of your dependency group (for instance, `test`):
+
+```toml
+[tool.poetry.group.test] # This part can be left out
+
+[tool.poetry.group.test.dependencies]
+pytest = "^6.0.0"
+pytest-mock = "*"
+```
+
+{{% note %}}
+All dependencies **must be compatible with each other** across groups since they will
+be resolved regardless of whether they are required for installation or not (see [Installing group dependencies]({{< relref "#installing-group-dependencies" >}})).
+
+Think of dependency groups as **labels** associated with your dependencies: they don't have any bearings
+on whether their dependencies will be resolved and installed **by default**, they are simply a way to organize
+the dependencies logically.
+{{% /note %}}
+
+The dependencies declared in `tool.poetry.dependencies` are part of an implicit `default` group.
+
+```toml
+[tool.poetry.dependencies] # Default dependency group
+httpx = "*"
+pendulum = "*"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^6.0.0"
+pytest-mock = "*"
+```
+
+{{% note %}}
+**A note about the `dev-dependencies` section**
+
+Any dependency declared in the `dev-dependencies` section will automatically be added to a `dev` group.
+So the two following notations are equivalent:
+
+```toml
+[tool.poetry.dev-dependencies]
+pytest = "^6.0.0"
+pytest-mock = "*"
+```
+
+```toml
+[tool.poetry.group.dev.dependencies]
+pytest = "^6.0.0"
+pytest-mock = "*"
+```
+
+Poetry will slowly transition away from the `dev-dependencies` notation which will soon be deprecated,
+so it's advised to migrate your existing development dependencies to the new `group` notation.
+{{% /note %}}
+
+### Optional groups
+
+A dependency group can be declared as optional. This makes sense when you have
+a group of dependencies that are only required in a particular environment or for
+a specific purpose.
+
+```toml
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+mkdocs = "*"
+```
+
+{{% warning %}}
+Optional group dependencies will **still** be resolved along other dependencies, so
+special care should be taken to ensure they are compatible with each other.
+{{% /warning %}}
+
+### Adding a dependency to a group
+
+The [`add`]({{< relref "cli#add" >}}) command is the preferred way to add dependencies
+to a group. This is done by using the `--group (-G)` option.
+
+```bash
+poetry add pytest --group test
+```
+
+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`.
+
+You can **exclude** one or more groups with the `--without` option:
+
+```bash
+poetry install --without test,docs
+```
+
+You can also opt in [optional groups]({{< relref "#optional-groups" >}}) by using the `--with` option:
+
+```bash
+poetry install --with docs
+```
+
+If you only want to install the **default**, non-grouped, dependencies, you can do so
+with the `--default` option:
+
+```bash
+poetry install --default
+```
+
+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.
+
+```bash
+poetry install --only docs
+```
+
+### Removing dependencies from a group
+
+The [`remove`]({{< relref "cli#remove" >}}) command supports a `--group` option
+to remove packages from a specific group:
+
+```bash
+poetry remove mkdocs --group docs
+```