Add a guide for publishing packages (#5794)

Closes https://github.com/astral-sh/uv/issues/5793

docs/guides/projects.md

@@ -173,4 +173,4 @@ See the documentation on [running commands](../concepts/projects.md#running-comm
 To learn more about working on projects with uv, see the [Projects concept](../concepts/projects.md)
 page and the [command reference](../reference/cli.md#uv).
 
-Or, read on to learn how to [run and install tools](./tools.md) with uv.
+Or, read on to learn how to [publish your project as a package](./publish.md).

docs/guides/publish.md

@@ -0,0 +1,50 @@
+# 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`.
+
+## Building your package
+
+Build your package with the official `build` frontend:
+
+```console
+$ uvx --from build pyproject-build
+```
+
+The build artifacts will be placed in `dist/`.
+
+## Publishing your package
+
+Publish your package with `twine`:
+
+```console
+$ uvx twine upload dist/*
+```
+
+!!! tip
+
+    To provide credentials, use the `TWINE_USERNAME` and `TWINE_PASSWORD` environment variables.
+
+## Installing your package
+
+Test that the package can be installed and imported with `uv run`:
+
+```console
+$ uv run --with <PACKAGE> --no-project -- python -c "import <PACKAGE>"
+```
+
+The `--no-project` flag is used to avoid installing the package from your local project directory.
+
+!!! tip
+
+    If you have recently installed the package, you may need to include the
+    `--refresh-package <PACKAGE>` option to avoid using a cached version of the package.
+
+## Next steps
+
+To learn more about publishing packages, check out the
+[PyPA guides](https://packaging.python.org/en/latest/guides/section-build-and-publish/) on building
+and publishing.
+
+Or, read on for more details about the concepts in uv.

docs/guides/scripts.md

@@ -210,4 +210,4 @@ for more details on requesting Python versions.
 
 To learn more about `uv run`, see the [command reference](../reference/cli.md#uv-run).
 
-Or, read on to learn how to to [work on projects](./projects.md).
+Or, read on to learn how to [run and install tools](./tools.md) with uv.

docs/guides/tools.md

@@ -153,3 +153,5 @@ $ uv tool install mkdocs --with mkdocs-material
 
 To learn more about managing tools with uv, see the [Tools concept](../concepts/projects.md) page
 and the [command reference](../reference/cli.md#uv-tool).
+
+Or, read on to learn how to to [work on projects](./projects.md).

mkdocs.template.yml

@@ -89,8 +89,9 @@ nav:
       - guides/index.md
       - Installing Python: guides/install-python.md
       - Running scripts: guides/scripts.md
-      - Working on projects: guides/projects.md
       - Using tools: guides/tools.md
+      - Working on projects: guides/projects.md
+      - Publishing packages: guides/publish.md
   - Concepts:
       - concepts/index.md
       - Projects: concepts/projects.md