docs: update reference for pixi build (#2735)

Co-authored-by: Tim de Jager <tim@prefix.dev>

docs/reference/pixi_manifest.md

@@ -787,22 +787,82 @@ When an environment comprises several features (including the default feature):
 - The `channels` of the environment is the union of the `channels` of all its features. Channel priorities can be specified in each feature, to ensure channels are considered in the right order in the environment.
 - The `platforms` of the environment is the intersection of the `platforms` of all its features. Be aware that the platforms supported by a feature (including the default feature) will be considered as the `platforms` defined at project level (unless overridden in the feature). This means that it is usually a good idea to set the project `platforms` to all platforms it can support across its environments.
 
+## Global configuration
+
+The global configuration options are documented in the [global configuration](../reference/pixi_configuration.md) section.
+
+
 ## Preview features
 Pixi sometimes introduces new features that are not yet stable, but that we would like for users to test out. These features are called preview features. Preview features are disabled by default and can be enabled by setting the `preview` field in the project manifest. The preview field is an array of strings that specify the preview features to enable, or the boolean value `true` to enable all preview features.
 
 An example of a preview feature in the project manifest:
 
-```toml title="Example preview features in the project manifest"
-[project]
+```toml title="pixi.toml"
+[workspace]
 name = "foo"
 channels = []
 platforms = []
-preview = ["new-resolve"]
+preview = ["pixi-build"]
 ```
 
 Preview features in the documentation will be marked as such on the relevant pages.
 
+## Pixi Build
 
-## Global configuration
+Pixi build is an experimental feature that requires `preview = ["pixi-build"]` to be set in `[workspace]`
 
-The global configuration options are documented in the [global configuration](../reference/pixi_configuration.md) section.
+### Workspace section
+
+Currently, `workspace` is an alias for `project` and we recommend using `workspace` instead of `project`,
+when making use of the `pixi-build` preview feature.
+To use this keyword the preview feature *does not* need to be enabled, but for now we do recommend it for that use-case solely.
+
+### Package section
+
+The package section is used to define the package that is built by the project.
+Pixi only allows this table if `preview = ["pixi-build"]` is set in `[workspace]`.
+
+```toml
+[package]
+version = "1.0.0"
+```
+
+### Host, Build, dependencies
+
+The package section re-uses the `host-dependencies` and `build-dependencies`,
+which you can read about here: [host-build-dependencies](#host-dependencies) and [build-dependencies](#build-dependencies).
+If you have the `preview = ["pixi-build"]` enabled these are interpreted as part of the package.
+
+### Run dependencies
+
+Run dependencies are dependencies that are required at runtime by your package.
+For Python packages, these are the most common dependency types.
+For compiled languages, these are less common and would basically be dependencies that you do not need when compiling the package but are needed when running it.
+
+```toml
+[package.run-dependencies]
+rich = "*"
+```
+
+### The `build-system`
+
+The build system specifies how the package can be built.
+The build system is a table that can contain the following fields:
+
+- `channels`: specifies the channels to get the build backend from.
+- `build-backend`: specifies the build backend to use. This is a table that can contain the following fields:
+  - `name`: the name of the build backend to use. This will also be the executable name.
+  - `version`: the version of the build backend to use.
+
+```toml
+[build-system] # (5)!
+build-backend = { name = "pixi-build-python", version = "*" }
+channels = [
+  "https://prefix.dev/pixi-build-backends",
+  "https://prefix.dev/conda-forge",
+]
+```
+
+!!! note
+    We are currently not publishing the backends on conda-forge, but will do so in the future.
+    For now the backends are published at "https://prefix.dev/pixi-build-backends".