docs: update docs about the new behavior of the build command

Author: finswimmer

docs/cli.md

@@ -200,18 +200,23 @@ The `build` command builds the source and wheels archives.
 poetry build
 ```
 
-Note that, at the moment, only pure python wheels are supported.
+The command will trigger the build system defined in the `pyproject.toml` file according to [PEP 517](https://peps.python.org/pep-0517/).
+If necessary the build process happens in an isolated environment.
 
 #### Options
 
 * `--format (-f)`: Limit the format to either `wheel` or `sdist`.
 * `--clean`: Clean output directory before building.
-* `--local-version (-l)`: Add or replace a local version label to the build.
+* `--local-version (-l)`: Add or replace a local version label to the build (deprecated).
 * `--output (-o)`: Set output directory for build artifacts. Default is `dist`.
+* `--config-settings=<key>=<value> (-c)`: Config settings to be passed to the build back-end. (multiple allowed)
 
 {{% note %}}
 When using `--local-version`, the identifier must be [PEP 440](https://peps.python.org/pep-0440/#local-version-identifiers)
 compliant. This is useful for adding build numbers, platform specificities etc. for private packages.
+
+`--local-version` is deprecated and will be removed in a future version of Poetry.
+Use `--config-settings local-version=<version>` instead.
 {{% /note %}}
 
 {{% warning %}}

docs/libraries.md

@@ -45,6 +45,16 @@ If you do not want to commit the lock file and you are using git, add it to the
 
 Before you can actually publish your library, you will need to package it.
 
+You need to define a build-system according to [PEP 517](https://peps.python.org/pep-0517/) in the `pyproject.toml` file:
+
+```toml
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+```
+
+Then you can package your library by running:
+
 ```bash
 poetry build
 ```
@@ -63,6 +73,21 @@ a `wheel`, the following files are included in the `.dist-info` directory:
 When building an `sdist`, the following files will be included in the root folder:
   - `LICENSE*`
 
+### Alternative build backends
+
+If you want to use a different build backend, you can specify it in the `pyproject.toml` file:
+
+```toml
+[build-system]
+requires = ["maturin>=0.8.1,<0.9"]
+build-backend = "maturin"
+```
+
+The `poetry build` command will then use the specified build backend to build your package in
+an isolated environment. Ensure you have specified any additional settings according to the
+documentation of the build backend you are using.
+
+
 Once building is done you are ready to publish your library.
 
 ## Publishing to PyPI