docs: build backend docs (#2844)

Author: tdejager

docs/build/backends.md

@@ -0,0 +1,24 @@
+To decouple the building of a conda package from pixi we provide something what are called build backends.
+These are essentially executables following a specific protocol that is implemented for both pixi and the build backend.
+This also allows for decoupling of the build backend from pixi and it's manifest specification.
+
+The backends we are currently developing are available in the following [conda channel](https://prefix.dev/channels/pixi-build-backends).
+And are being developed in the [pixi-build-backends](https://github.com/prefix-dev/pixi-build-backends) repository.
+
+### Installation
+When looking at the following build-section:
+
+```toml
+--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:build-system"
+```
+
+5. This will allow pixi to install desired backends from the `pixi-build-backends` channel, and any requirements from `conda-forge`. Backends are installed into isolated environments, and will be shared across pixi projects.
+
+### Overriding the Build Backend
+Sometimes you want to override the build backend that is used by pixi. Meaning overriding the backend that is specified in the [`[build-system]`](../reference/pixi_manifest.md#the-build-system). We currently have two environment variables that allow for this:
+
+1. `PIXI_BUILD_BACKEND_OVERRIDE`: This environment variable allows for overriding of one or multiple backends.  Use `{name}={path}` to specify a backend name mapped to a path and `,` to separate multiple backends.
+For example: `pixi-build-cmake=/path/to/bin,pixi-build-python` will:
+   1. override the `pixi-build-cmake` backend with the executable located at `/path/to/bin`
+   2. and will use the `pixi-build-python` backend from the `PATH`.
+2. `PIXI_BUILD_BACKEND_OVERRIDE_ALL`: If this environment variable is set to *some* value e.g `1` or `true`, it will not install any backends in isolation and will assume that all backends are overridden and available in the `PATH`. This is useful for development purposes. e.g `PIXI_BUILD_BACKEND_OVERRIDE_ALL=1 pixi install`

docs/reference/pixi_manifest.md

@@ -797,12 +797,8 @@ Pixi sometimes introduces new features that are not yet stable, but that we woul
 
 An example of a preview feature in the project manifest:
 
-```toml title="pixi.toml"
-[workspace]
-name = "foo"
-channels = []
-platforms = []
-preview = ["pixi-build"]
+```toml
+--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:preview"
 ```
 
 Preview features in the documentation will be marked as such on the relevant pages.
@@ -823,8 +819,7 @@ 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"
+--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:package"
 ```
 
 ### Host, Build, dependencies
@@ -840,8 +835,7 @@ 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 = "*"
+--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:run-dependencies"
 ```
 
 ### The `build-system`
@@ -855,14 +849,9 @@ The build system is a table that can contain the following fields:
   - `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",
-]
+--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:build-system"
 ```
 
 !!! 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".
+    For now the backends are published at [conda channel](https://prefix.dev/channels/pixi-build-backends).

docs/source_files/pixi_tomls/simple_pixi_build.toml

@@ -39,4 +39,9 @@ hatchling = "*"
 simple_python = { path = "." }
 # --8<-- [end:dependencies]
 
+# --8<-- [start:run-dependencies]
+[run-dependencies]
+rich = ">=13.9.4,<14"
+# --8<-- [end:run-dependencies]
+
 # --8<-- [end:full]

mkdocs.yml

@@ -126,11 +126,12 @@ nav:
       - Pytorch Installation: features/pytorch.md
   - Building Packages:
       - Getting started: build/getting_started.md
-      - Dependency Types: build/dependency_types.md
       - Tutorials:
           - Building a Python package: build/python.md
           - Building a C++ Package: build/cpp.md
           - Multiple Packages in Workspace: build/workspace.md
+      - Dependency Types: build/dependency_types.md
+      - Build Backends: build/backends.md
   - Advanced:
       - Authentication: advanced/authentication.md
       - Channel Logic: advanced/channel_priority.md