From f08cd2b9dc00da1f0beb9bb750e89d4bcb1a6583 Mon Sep 17 00:00:00 2001
From: Zanie Blue <contact@zanie.dev>
Date: Mon, 5 Aug 2024 16:12:37 -0500
Subject: [PATCH] Add a guide for publishing packages (#5794)

Closes https://github.com/astral-sh/uv/issues/5793
---
 docs/guides/projects.md |  2 +-
 docs/guides/publish.md  | 50 +++++++++++++++++++++++++++++++++++++++++
 docs/guides/scripts.md  |  2 +-
 docs/guides/tools.md    |  2 ++
 mkdocs.template.yml     |  3 ++-
 5 files changed, 56 insertions(+), 3 deletions(-)
 create mode 100644 docs/guides/publish.md

diff --git a/docs/guides/projects.md b/docs/guides/projects.md
index 3708b04d6..c49cfbb87 100644
--- a/docs/guides/projects.md
+++ b/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).
diff --git a/docs/guides/publish.md b/docs/guides/publish.md
new file mode 100644
index 000000000..14e53dc59
--- /dev/null
+++ b/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.
diff --git a/docs/guides/scripts.md b/docs/guides/scripts.md
index e7a595033..2af99db18 100644
--- a/docs/guides/scripts.md
+++ b/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.
diff --git a/docs/guides/tools.md b/docs/guides/tools.md
index a74bc7a2f..61dc5248d 100644
--- a/docs/guides/tools.md
+++ b/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).
diff --git a/mkdocs.template.yml b/mkdocs.template.yml
index 620d7eff8..7167ccd6a 100644
--- a/mkdocs.template.yml
+++ b/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