Add documentation for uv build (#6991)

docs/concepts/projects.md

@@ -513,6 +513,37 @@ dependencies listed.
 If working in a project composed of many packages, see the [workspaces](./workspaces.md)
 documentation.
 
+## Building projects
+
+To distribute your project to others (e.g., to upload it to an index like PyPI), you'll need to
+build it into a distributable format.
+
+Python projects are typically distributed as both source distributions (sdists) and binary
+distributions (wheels). The former is a `.tar.gz` file containing the project's source code along
+with some additional metadata, while the latter is a `.whl` file containing pre-built artifacts that
+can be installed directly.
+
+`uv build` can be used to build both source distributions and binary distributions for your project.
+By default, `uv build` will build the project in the current directory, and place the built
+artifacts in a `dist/` subdirectory:
+
+```console
+$ uv build
+$ ls dist/
+example-0.1.0-py3-none-any.whl
+example-0.1.0.tar.gz
+```
+
+You can build the project in a different directory by providing a path to `uv build`, e.g.,
+`uv build path/to/project`.
+
+`uv build` will first build a source distribution, and then build a binary distribution (wheel) from
+that source distribution.
+
+You can limit `uv build` to building a source distribution with `uv build --source`, a binary
+distribution with `uv build --binary`, or build both distributions from source with
+`uv build --source --binary`.
+
 ## Build isolation
 
 By default, uv builds all packages in isolated virtual environments, as per

docs/guides/projects.md

@@ -175,6 +175,24 @@ $ python example.py
 See the documentation on [running commands](../concepts/projects.md#running-commands) and
 [running scripts](../concepts/projects.md#running-scripts) in projects for more details.
 
+## Building distributions
+
+`uv build` can be used to build source distributions and binary distributions (wheel) for your
+project.
+
+By default, `uv build` will build the project in the current directory, and place the built
+artifacts in a `dist/` subdirectory:
+
+```console
+$ uv build
+$ ls dist/
+hello-world-0.1.0-py3-none-any.whl
+hello-world-0.1.0.tar.gz
+```
+
+See the documentation on [building projects](../concepts/projects.md#building-projects) for more
+details.
+
 ## Next steps
 
 To learn more about working on projects with uv, see the [Projects concept](../concepts/projects.md)

docs/guides/publish.md

@@ -1,8 +1,10 @@
 # Publishing a package
 
-uv does not yet have dedicated commands for building and publishing a package. Instead, you can use
-the PyPA tools [`build`](https://github.com/pypa/build) and
-[`twine`](https://github.com/pypa/twine), both of which can be invoked via `uvx`.
+uv supports building Python packages into source and binary distributions via `uv build`.
+
+As uv does not yet have a dedicated command for publishing packages, you can use the PyPA tool
+[`twine`](https://github.com/pypa/twine) to upload your package to a package registry, which can be
+invoked via `uvx`.
 
 ## Preparing your project for packaging
 
@@ -16,18 +18,17 @@ the effect of declaring a build system in the
 
 ## Building your package
 
-Build your package with the official `build` frontend:
+Build your package with `uv build`:
 
 ```console
-$ uvx --from build pyproject-build --installer uv
+$ uv build
 ```
 
-!!! note
-
-    Using `--installer uv` is not required, but uses uv instead of the default, pip, for faster
-    builds.
+By default, `uv build` will build the project in the current directory, and place the built
+artifacts in a `dist/` subdirectory.
 
-The build artifacts will be placed in `dist/`.
+Alternatively, `uv build <SRC>` will build the package in the specified directory, while
+`uv build --package <PACKAGE>` will build the specified package within the current workspace.
 
 ## Publishing your package