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

Author: finswimmer

docs/cli.md

@@ -206,12 +206,16 @@ Note that, at the moment, only pure python wheels are supported.
 
 * `--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=CONFIG-SETTINGS`:  Provide config settings that should be passed to backend in `<key>=<value>` format. (multiple values 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